joyent/node — pull request #3157 by gjtorikian (2012-04-21 21:02:32+00:00)
Title: Update doc sets to new format

@isaacs @piscisaureus

First, terribly sorry for the delay on this. I get blocked by a lot of work at work.

This PR represents the rewritten, reformatted documentation fork, hosted on NodeManual, up to latest, 0.6.15.

Off the top of my heads, syntactically, things that have changed everywhere are:

1. Consistency between using `{` `}` everywhere
2. Consistency in headings (`##` is always class; `###` is always members)
3. Dropped the use of `->` as a return signifier, in exchange for a simple `,`

Probably there's more. Point something out in a diff and I'll be able to explain it.

I tested this by using my API doc generation tool, [panino](https://github.com/gjtorikian/panino-docs). It uses a strict grammar for validating things, and doesn't take any bullshit.

The files are full of C9 snippets, which are just gists that are executable in [Cloud9 IDE](http://ww.c9.io). Even if I wasn't working there, I still feel strongly that having _live, executable code_ would be infinitely superior than static text, to novices and experts alike.

Beyond that, though, the effort at NodeManual to provide a consistent and helpful design towards accessing the API documentation is also something that should be strongly considered. Grouping reference material with tutorials just makes sense, and providing an easy navigation (beyond just straight Markdown to HTML conversion) is beneficial to everyone using, reading, and writing the docs.

If there are questions, ask away.