On 1 Apr 2010, at 00:45, Hugh Sasse wrote: > I was still talking about examples from print books that are out > there. Some will be made obsolete by more recent editions, we face > the same upper bounds imposed by availability of people to do this, > but I'm coming from the position that a continual criticism of Ruby > has been the limits on its documentation. Provision of these > corrections seems like it could be a good aspiration, even if we > only make limited progress.
I agree wholeheartedly. The discussion always leads down the same path when I talk to people about it, rubyists seem to now have a culture of reading the code, and whilst that may breed better programmers in the end, it really hinders beginners. Updating our core documentation sources is a good start, and I've done a pass this evening as I say. Moving forward, we do need to encourage better documentation procedures, however, this requires some work on our infrastructure too, and ideally people need to stop blogging before doing documentation, or adding their blog posts to a doc/ directory or some suitably patchable place. >> If you have more specific updates or have a moment to review the changes, >> further input would be welcome. > > I'm clearly not looking in the right place, bowl me the URL and I'll see > if I've anything useful to add. My pass was through the user guide[1] primarily to look for examples that include deprecated code / apis, and update the markup to be slighly more presentable. I also added notes on `gem push` in the appropriate places. General consensus is that the command reference book[2] should be merged (where appropriate) into the docs inside 'gem help', and then removed or significantly cut down, to reduce maintenance load. [1] http://docs.rubygems.org/read/book/1 [2] http://docs.rubygems.org/read/book/2 _______________________________________________ Rubygems-developers mailing list http://rubyforge.org/projects/rubygems Rubygems-developers@rubyforge.org http://rubyforge.org/mailman/listinfo/rubygems-developers
