Ask HN: awesome web-based documentation? | Hacker News Reader

Ask HN: awesome web-based documentation?

38 pointsjon_dahl46 comments

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?

View on HN

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.

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.

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.

Agreed. It would also be worth considering using Stack Overflow-style voting for comments.

Pet weekend project / software as a service?

I know with Disqus comments you can sort by Most Popular or Highest Rated. Not sure if you can default to one of those.

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.

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.

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/

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/

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

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

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

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.

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

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.

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.

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.

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

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...

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

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

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

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

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

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/

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.

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.

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/

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.

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

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)

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

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.)

PHP.Net and Django.

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

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

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

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.

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

A step-by-step example helps alot.

Surprised noone has mentioned Heroku. Simple, accessible, and generally easy to navigate. http://docs.heroku.com/

I like racket's documentation (although some more examples would be nice): http://docs.racket-lang.org/

For reference documentation, I find this one great: http://railsapi.com/doc/rails-v3.0.1/

Tornado: http://tornadoweb.org/

Django: http://djangoproject.com/

NOT Python.

Why, I really like Python's documentation. Did you mean that the Python documentation is NOT good?

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.

http://readthedocs.org/

Cool idea for Sphinx-based docs.

Slicehost's documentation is the BOMB. I aspire to be like PickledOnion one day.

Django and Linode

Reply on news.ycombinator.com