Ryan Tomayko

pocco —

Python version of Docco, the quick-and-dirty, hundred-line-long, literate-programming-style documentation generator:

8888888b.
888   Y88b
888    888
888   d88P  .d88b.    .d8888b  .d8888b  .d88b.
8888888P"  d88""88b  d88P"    d88P"    d88""88b
888        888  888  888      888      888  888
888        Y88..88P  Y88b.    Y88b.    Y88..88P
888         "Y88P"    "Y8888P  "Y8888P  "Y88P"

All together, we have Docco, Rocco, shocco, and now Pocco. Jeremy observes, “It’s a whole little adorable family of midget programs now…”

man what —

Chris Wanstrath makes the case for UNIX man pages and tours through a bunch of tools for creating, finding, and reading them.

docco —

Okay, this is the project used to generate the previously linked CoffeeScript documentation. It’s a “quick-and-dirty, hundred-line-long, literate-programming-style documentation generator.” It pulls out comments, applies markdown, and then runs the code through pygments for syntax highlighting.

Beautiful.

Annotated CoffeeScript Grammar —

I don’t believe I’ve ever seen code annotated like this before:

It’s perfect.

The HTML is <table> based. Each segment is an anchored <tr> with the left cell holding the annotations and the right cell holding the code. I’d probably flip them around but the overall effect is wonderful.

gem-man(1) -- view a gem's man page —

Perfect. This was a huge piece missing from Ron and I had no clue how to address it. Chris’s gem extension adds a gem man command that brings up the man page for any gem and works with any gem that includes normal roff man pages.

ron(7) -- the opposite of roff —

I’ve released a tool for authoring UNIX manual pages using a markdown-ish source format:

Ron is a humane text format and toolchain for creating UNIX man pages, and things that appear as man pages from a distance. Use it to build and install standard UNIX roff man pages or to generate nicely formatted HTML manual pages for the web.

It still needs some work but can produce useful output for both roff and HTML. The sources are on GitHub.

Writing good documentation —

Jacob Kaplan-Moss:

It’s really tempting to use an auto-documentation tool like Javadoc or RDoc for reference material.

Don’t.

Auto-generated documentation is almost worthless. At best it’s a slightly improved version of simply browsing through the source, but most of the time it’s easier just to read the source than to navigate the bullshit that these autodoc tools produce. About the only thing auto-generated documentation is good for is filling printed pages when contracts dictate delivery of a certain number of pages of documentation. I feel a particularly deep form of rage every time I click on a “documentation” link and see auto-generated documentation.

Hate that shit.

You know what I want? Man pages. For everything. Wouldn’t it be cool if you didn’t have to write roff?

Why's (Poignant) Guide to Ruby —

I’ll admit, I’ve been holding out, hoping that _why’s disappearance was just a big misunderstanding. But at this point, I don’t think he could come back even if it were a big misunderstanding. Here’s a mirror (thanks mislav + GitHub Pages) of the Poignant Guide – the canonical reference for how to be. It’s our GOF; our SICP. I don’t think I’ve ever been so in awe of a piece of technical literature. Now it just makes me sad.

Hanna - A Better RDoc —

This is the template used to generate the HAML RDoc. It’s a massive improvement over the default template shipped with rdoc. I can almost stomach rdoc with this — almost.

Google Doctype —

What Mark Pilgrim has been working on at Google for the past year or so: an encyclopedia of web development.

Git Magic —

All manners of good stuff here.

Prototype Javascript Framework —

Documentation, finally!