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

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

~~~
makmanalp
Pet weekend project / software as a service?

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

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

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

~~~
jollyjerry
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

------
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...](http://documentcloud.github.com/underscore/docs/underscore.html)

~~~
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...](http://msdn.microsoft.com/en-
us/library/preferences/experience/?returnurl=%252fen-
us%252flibrary%252fms123401)

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

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

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

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

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

------
bmelton
Tornado: <http://tornadoweb.org/>

Django: <http://djangoproject.com/>

NOT Python.

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

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

------
gkelly
<http://readthedocs.org/>

Cool idea for Sphinx-based docs.

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

------
mkramlich
Django and Linode

