Documentation is freaking awesome
warpspire.com
warpspire.com
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.
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.
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)...
But see, that's what kept it from being really good in my opinion. Sure, it's an example of good tutorial-based documentation. The tutorial/reference divide seems kind of artificial to me though. It leaves you with documentation you can use as a beginner and documentation you can use as an advanced user, but nothing to help you move between the two. In contrast, django's documentation tends to be a good mix between the two.