6 ms·
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?
- steveklabnik 16y agoThe best documentation I've ever read is Heroku's new addon provider docs: https://addons.heroku.com/provider https://addons.heroku.com/provider Click any of the links on the bottom. They're gorgeous, informative, and have fantastic examples.
- makethetick 16y agojQuery and CakePHP have been very helpful in the past. http://docs.jquery.com/Main_Page http://docs.jquery.com/Main_Page http://book.cakephp.org/ 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/ http://www.php.net/manual/en/
- josegonzalez 16y agoIt'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 16y agoThe 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.
- dstik 16y agoIn 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.html http://documentcloud.github.com/underscore/docs/underscore.h...
- Dylanfm 16y agoAlong with Coffeescript's docs and annotated source http://jashkenas.github.com/coffee-script/ http://jashkenas.github.com/coffee-script/
- stevelosh 16y agoFlask'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/ http://flask.pocoo.org/
- gpjt 16y agoI 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/ http://sphinx.pocoo.org/
- aaronmoodie 16y agoAnother vote for Flask. The Sintra docs are also quite good. http://www.sinatrarb.com/documentation http://www.sinatrarb.com/documentation
- jollyjerry 16y agoRelated 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/ http://guides.rubyonrails.org/ that are topic based are really helpful
- nicksergeant 16y agoThought I'd get to Flask before Steve, but clearly I was mistaken. Another vote for Flask. Gorgeous.
- nicksergeant 16y agoAlso: 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.
- tgriesser 16y agoThis is my favorite documentation... http://codeigniter.com/user_guide/ 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
- mkramlich 16y agoDjango and Linode
- cheald 16y agoThe Mongoid docs are really pretty: http://mongoid.org/docs/installation/ 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/ 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 http://rdoc.info/github/mislav/will_paginate/master/frames
- makmanalp 16y agohttp://jashkenas.github.com/docco/ http://jashkenas.github.com/docco/ <- good doc system AND documentation
- xiongchiamiov 16y agoI'm rather fond of Django's: http://docs.djangoproject.com/en/1.2/ http://docs.djangoproject.com/en/1.2/
- baddox 16y agoSimilarly, http://djangobook.com/en/2.0/ http://djangobook.com/en/2.0/ . I really like the user interface for this one.
- makmanalp 16y agohttp://us3.php.net/strstr 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.
- kaerast 16y agoThe 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.
- auxbuss 16y agoI 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.
- gabrielroth 16y agoAgreed. It would also be worth considering using Stack Overflow-style voting for comments.
- Nick_C 16y agoI 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.
- RyanDScott 16y agoI like the Google Closure documentation. It has a nice search functionality. http://closure-library.googlecode.com/svn/docs/index.html http://closure-library.googlecode.com/svn/docs/index.html
- cies 16y agoi 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.
- yread 16y agoI really like msdn. Especially when you switch the presentation to LightWeight of Script free http://msdn.microsoft.com/en-us/library/preferences/experience/?returnurl=%252fen-us%252flibrary%252fms123401 http://msdn.microsoft.com/en-us/library/preferences/experien...
- vinnyglennon 16y agohttp://blog.dexy.it/247 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)
- desigooner 16y agoPHP.Net and Django. PHP's multiple examples are really neat. that and people commenting.
- olalonde 16y agoFor reference documentation, I find this one great: http://railsapi.com/doc/rails-v3.0.1/ http://railsapi.com/doc/rails-v3.0.1/
- gkelly 16y agohttp://readthedocs.org/ http://readthedocs.org/ Cool idea for Sphinx-based docs.
- stephenou 16y agoCodeIgniter: http://codeigniter.com/user_guide 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.
- d4ft 16y agoSurprised noone has mentioned Heroku. Simple, accessible, and generally easy to navigate. http://docs.heroku.com/ http://docs.heroku.com/
- cd34 16y agoSQLAlchemy http://www.sqlalchemy.org/docs/ http://www.sqlalchemy.org/docs/ Mako Templates http://www.makotemplates.org/docs/ 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/ http://docs.pylonshq.com/ Documentation + 100% test coverage and also a very responsive development team.
- j_baker 16y agoI 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.
- bmelton 16y agoTornado: http://tornadoweb.org/ http://tornadoweb.org/ Django: http://djangoproject.com/ http://djangoproject.com/ NOT Python.
- dheerosaur 16y agoWhy, I really like Python's documentation. Did you mean that the Python documentation is NOT good?
- bmelton 16y agoI'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.
- j_baker 16y agoI like racket's documentation (although some more examples would be nice): http://docs.racket-lang.org/ http://docs.racket-lang.org/
- subpixel 16y agoI think the Compass docs rock: http://compass-style.org/docs/reference/compass/ http://compass-style.org/docs/reference/compass/ (But if I remember correctly, they don't rock in all browsers.)
- imwilsonxu 16y agoPlayframework: http://www.playframework.org/documentation/1.1/guide1 http://www.playframework.org/documentation/1.1/guide1 A step-by-step example helps alot.
- ludwigvan 16y agoNo one mentioned Apple's docs? I find them pretty well-written. http://developer.apple.com/library/ios/navigation/ http://developer.apple.com/library/ios/navigation/
- MarinaMartin 16y agoSlicehost's documentation is the BOMB. I aspire to be like PickledOnion one day.
- audionerd 16y agoNanoc has excellent, comprehensive documentation with great typography and style in the layout: http://nanoc.stoneship.org/docs/ http://nanoc.stoneship.org/docs/ backbone.js docs are concise and easy to follow, also well designed: http://documentcloud.github.com/backbone/ http://documentcloud.github.com/backbone/