News for hackers. Stuff that matters.

Ask HN: awesome web-based documentation?

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?

( 46 comments | 38 points | on HN )
Re:Ask HN: awesome web-based documentation? by makmanalp on Thursday November 18, 2010 @06:54PM (#1919847)
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.
Re:Ask HN: awesome web-based documentation? by auxbuss on Thursday November 18, 2010 @07:18PM (#1919913)
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.

Re:Ask HN: awesome web-based documentation? by gabrielroth on Thursday November 18, 2010 @08:54PM (#1920101)
Agreed. It would also be worth considering using Stack Overflow-style voting for comments.
Re:Ask HN: awesome web-based documentation? by makmanalp on Thursday November 18, 2010 @11:02PM (#1920390)
Pet weekend project / software as a service?
Re:Ask HN: awesome web-based documentation? by Heff on Friday November 19, 2010 @05:58PM (#1923174)
I know with Disqus comments you can sort by Most Popular or Highest Rated. Not sure if you can default to one of those.
Re:Ask HN: awesome web-based documentation? by kaerast on Thursday November 18, 2010 @07:08PM (#1919884)
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.
Re:Ask HN: awesome web-based documentation? by Nick_C on Thursday November 18, 2010 @09:32PM (#1920194)
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.

Re:Ask HN: awesome web-based documentation? by bmelton on Friday November 19, 2010 @10:25AM (#1921616)
PHP's comments are moderated, and I don't believe that a comment is even allowed on the page until it's passed at least some moderator's standards.

That said, I think the comments absolutely belong there, as it's typically where I find the gotchas that don't make it into the language docs. Comments like "you can use this function most of the time, but if you're foo, functionB() is faster for those cases" are invaluable in optimization, and are seldom well-published in official language docs.

What that means is that I can be a slow expert in the PHP language versus the years of experience it would take me to divine those truths working in another language.

Re:Ask HN: awesome web-based documentation? by stevelosh on Thursday November 18, 2010 @06:29PM (#1919758)
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/

Re:Ask HN: awesome web-based documentation? by gpjt on Thursday November 18, 2010 @06:34PM (#1919779)
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/

Re:Ask HN: awesome web-based documentation? by aaronmoodie on Thursday November 18, 2010 @06:43PM (#1919811)
Another vote for Flask. The Sintra docs are also quite good. http://www.sinatrarb.com/documentation
Re:Ask HN: awesome web-based documentation? by jollyjerry on Thursday November 18, 2010 @09:05PM (#1920131)
Related to Sinatra, the Padrino docs and guides are really good. On top of reference style documentation, guides and tutorials like the ones at http://guides.rubyonrails.org/ that are topic based are really helpful
Re:Ask HN: awesome web-based documentation? by nicksergeant on Thursday November 18, 2010 @08:26PM (#1920044)
Thought I'd get to Flask before Steve, but clearly I was mistaken. Another vote for Flask. Gorgeous.
Re:Ask HN: awesome web-based documentation? by nicksergeant on Thursday November 18, 2010 @08:27PM (#1920045)
Also: Flask's documentation is so gorgeous it almost convinced me I needed to use the framework even though I knew didn't need to use it.
Re:Ask HN: awesome web-based documentation? by tgriesser on Thursday November 18, 2010 @06:37PM (#1919792)
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

Re:Ask HN: awesome web-based documentation? by stephenou on Thursday November 18, 2010 @07:35PM (#1919942)
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.

Re:Ask HN: awesome web-based documentation? by cd34 on Thursday November 18, 2010 @08:06PM (#1920005)
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.

Re:Ask HN: awesome web-based documentation? by j_baker on Thursday November 18, 2010 @08:23PM (#1920036)
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.
Re:Ask HN: awesome web-based documentation? by makmanalp on Thursday November 18, 2010 @06:52PM (#1919840)
http://jashkenas.github.com/docco/ <- good doc system AND documentation
Re:Ask HN: awesome web-based documentation? by dstik on Thursday November 18, 2010 @06:20PM (#1919732)
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...
Re:Ask HN: awesome web-based documentation? by Dylanfm on Thursday November 18, 2010 @06:30PM (#1919761)
Along with Coffeescript's docs and annotated source http://jashkenas.github.com/coffee-script/
Re:Ask HN: awesome web-based documentation? by yread on Thursday November 18, 2010 @07:02PM (#1919862)
I really like msdn. Especially when you switch the presentation to LightWeight of Script free

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

Re:Ask HN: awesome web-based documentation? by xiongchiamiov on Thursday November 18, 2010 @06:54PM (#1919846)
I'm rather fond of Django's: http://docs.djangoproject.com/en/1.2/
Re:Ask HN: awesome web-based documentation? by baddox on Thursday November 18, 2010 @07:17PM (#1919909)
Similarly, http://djangobook.com/en/2.0/ . I really like the user interface for this one.
Re:Ask HN: awesome web-based documentation? by makethetick on Thursday November 18, 2010 @06:08PM (#1919687)
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/

Re:Ask HN: awesome web-based documentation? by josegonzalez on Thursday November 18, 2010 @08:48PM (#1920089)
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.

Re:Ask HN: awesome web-based documentation? by bluedevil2k on Thursday November 18, 2010 @09:05PM (#1920130)
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.
Re:Ask HN: awesome web-based documentation? by audionerd on Thursday December 02, 2010 @12:42AM (#1961166)
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/

Re:Ask HN: awesome web-based documentation? by steveklabnik on Thursday November 18, 2010 @05:41PM (#1919596)
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.

Re:Ask HN: awesome web-based documentation? by cheald on Thursday November 18, 2010 @06:51PM (#1919837)
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

Re:Ask HN: awesome web-based documentation? by vinnyglennon on Thursday November 18, 2010 @07:09PM (#1919887)
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)
Re:Ask HN: awesome web-based documentation? by RyanDScott on Thursday November 18, 2010 @06:56PM (#1919850)
I like the Google Closure documentation. It has a nice search functionality. http://closure-library.googlecode.com/svn/docs/index.html
Re:Ask HN: awesome web-based documentation? by subpixel on Thursday November 18, 2010 @09:43PM (#1920211)
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.)

Re:Ask HN: awesome web-based documentation? by desigooner on Thursday November 18, 2010 @07:17PM (#1919904)
PHP.Net and Django.

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

Re:Ask HN: awesome web-based documentation? by ludwigvan on Friday November 19, 2010 @08:17AM (#1921314)
No one mentioned Apple's docs? I find them pretty well-written.

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

Re:Ask HN: awesome web-based documentation? by cies on Thursday November 18, 2010 @07:01PM (#1919861)
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.

Re:Ask HN: awesome web-based documentation? by imwilsonxu on Thursday November 18, 2010 @10:13PM (#1920283)
Playframework: http://www.playframework.org/documentation/1.1/guide1

A step-by-step example helps alot.

Re:Ask HN: awesome web-based documentation? by d4ft on Thursday November 18, 2010 @07:51PM (#1919978)
Surprised noone has mentioned Heroku. Simple, accessible, and generally easy to navigate. http://docs.heroku.com/
Re:Ask HN: awesome web-based documentation? by j_baker on Thursday November 18, 2010 @08:27PM (#1920046)
I like racket's documentation (although some more examples would be nice): http://docs.racket-lang.org/
Re:Ask HN: awesome web-based documentation? by olalonde on Thursday November 18, 2010 @07:17PM (#1919910)
For reference documentation, I find this one great: http://railsapi.com/doc/rails-v3.0.1/
Re:Ask HN: awesome web-based documentation? by bmelton on Thursday November 18, 2010 @08:22PM (#1920035)
Re:Ask HN: awesome web-based documentation? by dheerosaur on Thursday November 18, 2010 @11:31PM (#1920433)
Why, I really like Python's documentation. Did you mean that the Python documentation is NOT good?
Re:Ask HN: awesome web-based documentation? by bmelton on Friday November 19, 2010 @10:20AM (#1921601)
I'm not crazy about the formatting, honestly. I prefer more conversational documentation, personally, and Python's documentation always reminds me of Javadoc, which I generally abhor.

I think the one thing that I dislike, if I had to pick out something in particular, is that they include a function reference inline with discussion about it. I'd prefer to see them separated, though I freely admit that may just be me being peculiar, rather than any particular deficiency in the docs.

Re:Ask HN: awesome web-based documentation? by gkelly on Thursday November 18, 2010 @07:18PM (#1919916)
http://readthedocs.org/

Cool idea for Sphinx-based docs.

Re:Ask HN: awesome web-based documentation? by MarinaMartin on Friday November 19, 2010 @09:53PM (#1923685)
Slicehost's documentation is the BOMB. I aspire to be like PickledOnion one day.
Re:Ask HN: awesome web-based documentation? by mkramlich on Thursday November 18, 2010 @06:47PM (#1919823)
Django and Linode