Hacker News Reader

Comment by kneath | Hacker News Reader

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.

View on HN

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

> Rails Guides is in there as an example of Tutorial type documentation and a way to leverage your project's website.

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.

Your talk was great! Thanks for presenting at MagicRuby.

Reply on news.ycombinator.com