Ask HN: awesome web-based documentation?

[jon_dahl]

We're currently rewriting our documentation for Zencoder, and are looking for examples of good web-based docs. For example, I still use Slicehost tutorials for Linux work (http://articles.slicehost.com); they're really well done how-to guides for web hosting and linux sysadmin work.

Any other examples of good doc systems, or tips for creating effective documentation?

[makmanalp]

http://us3.php.net/strstr -> The php docs have one redeeming quality that I wish all of them had: comments! Whenever there is odd behavior, a gotcha, a pitfall, it's always in the comments. No need to trawl through blogs and mailing lists.

[auxbuss]

I agree, and have an additional comment:

If the comments become part of the documentation, then you need to ruthlessly edit them to remove incorrect advice, duplication, and redundancy. If you simply leave everything there forever, then the comments become worthless. Integrity of information is everything.

[kaerast]

The php docs are also nice in that it's really easy to work out a url to the document you need; it's almost always just php.net/functionname, and if it's not then you still get something useful.

[Nick_C]

I loathe PHP's docs for two reasons: - the colour choice; - the comments.

The colour choice for code examples is orange on gray. This is almost impossible to read for colour-blind people. I have to squint to make out each character. I can't get in to a flow and read the code, I have to decode each character then put them together to read the snippet in its entirety.

I don't think user-land comments have any place in documentation. The docs form part of the official specs for the language and, personally, I find user comments create too much unintentional confusion. You often find well-intentioned amateurs make basic errors in PHP's doc examples. User comments can be great for examples, but they belong in a separate place, say, a wiki.

An example of good docs IMO is Python's. A nice helpful topic bar on the left, and careful docs on the right.

[stevelosh]

Flask's documentation is my favorite. I sat down and read all of it one night just because it was so beautiful and readable.

http://flask.pocoo.org/

[gpjt]

I think they generated it using Sphinx, which I heartily recommend as a tool -- you write your docs in REST, and it generates HTML (with built-in JavaScript search), PDF or other formats. It was developed for the latest version of the Python docs.

http://sphinx.pocoo.org/

[aaronmoodie]

Another vote for Flask. The Sintra docs are also quite good. http://www.sinatrarb.com/documentation

[nicksergeant]

Thought I'd get to Flask before Steve, but clearly I was mistaken. Another vote for Flask. Gorgeous.

[tgriesser]

This is my favorite documentation... http://codeigniter.com/user_guide/

The table of contents dropdown tab at the top is a cool way to organize the different categories of information... the styling of the docs is also consistent and easily legible

[stephenou]

CodeIgniter: http://codeigniter.com/user_guide

The interface is really simplistic which allows me to read the documentation a lot longer than other site (ex. php.net). Also, it's very well-organized and completed, I can go there every time I have a question about the framework and don't need to Google much.

[cd34]

SQLAlchemy http://www.sqlalchemy.org/docs/

Mako Templates http://www.makotemplates.org/docs/

Beautifully written, well documented, plenty of examples and use cases... and then a super responsive developer that appears to never sleep and answers questions posted on the mailing list within minutes.

Pyramid (The Pylons/BFG Merger) http://docs.pylonshq.com/

Documentation + 100% test coverage and also a very responsive development team.

[j_baker]

I can vouch for the developer of Mako and SQLAlchemy. Michael Bayer has even added features to SQLAlchemy just to get one of my previous employers to use it.

[makmanalp]

http://jashkenas.github.com/docco/ <- good doc system AND documentation

[dstik]

In addition to the great links already posted, if you are looking to really describe your code, check out the Underscore.js docs: http://documentcloud.github.com/underscore/docs/underscore.h...

[Dylanfm]

Along with Coffeescript's docs and annotated source http://jashkenas.github.com/coffee-script/

[yread]

I really like msdn. Especially when you switch the presentation to LightWeight of Script free

http://msdn.microsoft.com/en-us/library/preferences/experien...

[xiongchiamiov]

I'm rather fond of Django's: http://docs.djangoproject.com/en/1.2/

[baddox]

Similarly, http://djangobook.com/en/2.0/ . I really like the user interface for this one.

[makethetick]

jQuery and CakePHP have been very helpful in the past.

http://docs.jquery.com/Main_Page

http://book.cakephp.org/

Also, the PHP documentation is very good. The layout could be better but it's kept really simple with lots of examples to help you out.

http://www.php.net/manual/en/

[josegonzalez]

It's funny because everyone ALWAYS complains about the CakePHP documentation on #cakephp, but whenever it is pointed out that it is a wiki, the following excuses come up:

- I'm too busy

- It should already be there, this is a common problem

- I don't know enough to edit

- How do I make an account

Good documentation for a community is hard.

[bluedevil2k]

The jQuery docs were MUCH better before the 1.3 release. They now use "plain speak" descriptions of what each function does and sorts them alphabetically. They used to be coder friendly descriptions grouped together by functionality. For example, the show() and hide() used to be next to each other, now they're not.

[audionerd]

Nanoc has excellent, comprehensive documentation with great typography and style in the layout:

http://nanoc.stoneship.org/docs/

backbone.js docs are concise and easy to follow, also well designed:

http://documentcloud.github.com/backbone/

[steveklabnik]

The best documentation I've ever read is Heroku's new addon provider docs: https://addons.heroku.com/provider

Click any of the links on the bottom. They're gorgeous, informative, and have fantastic examples.

[cheald]

The Mongoid docs are really pretty: http://mongoid.org/docs/installation/

People either love or hate the Ruby docs - I like them, personally. I never have issues finding what I need. http://www.ruby-doc.org/core/

I also like the rdoc.info stuff. It's a bit spartan, but it's usable, as long as the gem author actually included documentation. http://rdoc.info/github/mislav/will_paginate/master/frames

[vinnyglennon]

http://blog.dexy.it/247 should be ready soon. The product allows your documenation to be ran like normal code, no matter the language, therefore you will always have working docs(if regularly running it against a vm)

[RyanDScott]

I like the Google Closure documentation. It has a nice search functionality. http://closure-library.googlecode.com/svn/docs/index.html

[subpixel]

I think the Compass docs rock: http://compass-style.org/docs/reference/compass/

(But if I remember correctly, they don't rock in all browsers.)

[desigooner]

PHP.Net and Django.

PHP's multiple examples are really neat. that and people commenting.

[ludwigvan]

No one mentioned Apple's docs? I find them pretty well-written.

http://developer.apple.com/library/ios/navigation/

[cies]

i like publican, you have to feed it docbook (xml), but it then outputs pdf/html/epub, allows for pot-po based translations and is nicely stylable.

in one setup i put asciidoc (a wiki-syntax-to-docbook tool) before publican to make writing/editing the docs more straight forward.

i cannot give you one-size-fits-all documentation tips, it depends heavily on what document you work on (api docs, a user guide, etc.) and what is the target audience.

personally i like to avoid the word "you" in documentation.

[imwilsonxu]

Playframework: http://www.playframework.org/documentation/1.1/guide1

A step-by-step example helps alot.