

Documentation is freaking awesome - dhotson
http://warpspire.com/talks/documentation/

======
forsaken
Agreed. I'm currently running a site over at <http://readthedocs.org/> which
is meant to be your one-stop shop for Sphinx documentation. It has most of the
big python projects on it, and hopefully as sphinx gets more popular, it will
attract others as well. For example, we are mirroring the Varnish docs.

We also had a kick-ass designer help us on it, so the site actually looks
rather pretty.

I've had a number of people tell me that RTD has been something that has
spurred them to write documentation, so I'm really happy with the results thus
far.

~~~
ylem
Thanks for this! It is great!!!!

------
jarin
Ok, so I would love to find something like Yard but focused around web service
APIs. Anyone know of anything like that?

------
j_baker
Ok, Rails Guides definitely deserves mention for being one of the _prettiest_
sources of documentation, but I don't know that it really deserves mention as
being a great example of good documentation. I mean it isn't bad, but django's
documentation beats the pants off of it.

~~~
kneath
I guess without hearing my talk, this might be confusing. Rails Guides is in
there as an example of Tutorial type documentation and a way to leverage your
project's website.

This presentation was prepared for a Ruby conference, so the examples were
geared toward the audience (ruby & rails centric).

More importantly though: When's the last time you used Rails Guides? There was
a time when Django's documentation _was_ light years better than anything
Rails prepared, but I would very much disagree saying Rails Guides are poor in
comparison today.

~~~
moe
As someone who originally came from python and recently learned rails (well,
still in the process) using the official docs and the railsbook I have to say:
Sorry but yes, the Rails docs (at least the ones I have found) _are_ poor in
comparison.

And it gets only worse when you look beyond Rails; documentation in the ruby
realm (gems et al) is almost always lacking in quantity and underwhelming in
quality to a former pythonista.

Admittedly it's a bit of an unfair comparison, considering python docs are -
on average - the best I've ever seen. And considering python is a bit easier
to document formally due to less magic in the language.

But it's also a mindset thing. Python has doc-strings and doc-test baked right
into the language. Sphinx and epydoc are so ridiculously good, it's not funny.

On the ruby side documentation seems more like an afterthought. RDoc itself is
poorly documented (oh the irony!), and the only tool to bake readable output
from it (YARD) is a fairly recent invention. I haven't found an equivalent to
sphinx, yet.

The obsession that the python community applies to documentation seems to be
spent on testing-tools in the ruby camp. This is, however, a rather
unfortunate choice of priorities when you look at the (lack of) documentation
for even the most popular testing tools (e.g. RSpec)...

------
davnola
Documentation is freaking awesome, but _executable_ documentation is even more
awesome e.g. <http://relishapp.com/rspec>

