Friday, August 24, 2007

the state of ruby documentation, part 1 (a rant)

[geek alert: if you're not a computer geek, this may not be of much interest.]

OK, so I just saw this in some documentation:
This article is part of the confusing world of Authentication in Rails. Feel free to get lost in a gazillion of nearly useless and/or outdated Wikipages.

I really like a lot of things about the Ruby and Rails communities. Stale documentation, though, is a glaring exception (and this isn't the only example -- rails docs without using migrations (or outdated versions) create a whole category of additional exceptions).

And I want it to change.

For my part, I will make a specific effort to help improve the documentation. I hope others will do the same. And in any case, whether you write anything new or not, PLEASE please please, don't encourage (including by standing by idly and allowing) folks to continue propagating the defeatist attitude above.

There. I've just started on my part, and re-written the above-quoted text to be more hopeful, and also added to the other linked page so it's easier for folks to know how to help. May these be the first of many edits I shall do.

No comments: