From: Phillip Gawlowski Date: 2011-08-03T05:10:13+09:00 Subject: Re: Documentation Improvement Proposal On Tue, Aug 2, 2011 at 9:46 PM, Steve Klabnik wrote: > >> Do you mean in appearance or approach to openness? > > They call them 'bureaucrats' for a reason. A million little dictators, > lords over their domain... and have a disagreement, and they throw all > kinds of jargon and rules at you. I was too terse, it appears. I have *not* meant Wikipedia's content police, but the collaborative aspect of creating documents and documentation. > Yes. Documentation should be crafted. Tons of people throwing random > code samples at the bottom of the page is not helpful. See Eric's > response: "User contributions should be aggressively curated to fold > documentation improvements back in to the source material and remove > bug reports and "how do I use this?" type questions." I can't repeat > this enough. Which means that some review is necessary, so a staging process fro authoring, to review/editing to publishing needs to exist. For comments as well, if they should be allowed at all. > I am not ultra-familiar, I just know that it exists, that they care > about it, and that often, I hear "Python is better than Ruby because > Ruby's documentation sucks and Python's is great." And I think that's > pretty much true. I'd most certainly be willing to investigate their > process, ping some people to ask them about it, etc, if that'll help > move things forward. I think that it's the result of a much more stringent approach to language features/STDLIB/API, that reminds me of a bazaar-style Java Community Process. So, features get discussed for a while before they get implemented, down to the details of how something should work. That makes it much easier to write documentation. Ruby is much more, well, freewheeling in its approach to adding features/STDLIB/API, and grows more organically. Thus, I have to get Rake documentation on one website, RubyGems documentation on another website, and Ruby's documentation on yet a third site, and none of them is docs.ruby-lang.org *nor* api.ruby-lang.org, and RDoc is somewhere else again. > The biggest problem that I have with Ruby's documentation is that it's > all just API docs. That's fine, but there needs to be guides-style > documentation, too. I get newbies that finish the paltry lessons I've > finished for Hackety Hack asking me what next to read all the time, > and I have to point them at the Pickaxe or the Poignant Guide. The > fact that I can't simply point them at some sort of officialish > documentation is pretty poor. Someone, somewhere must have an archive of ruby-talk in mbox format. Provided I can get my hands on such a motherlode of archives, I'd be more than willing to go through the last two or three years worth of messages to find "How do I?" type questions. Guides can be built from there (and maybe revive the ruby-talk FAQ?). -- Phillip Gawlowski phgaw.posterous.com | twitter.com/phgaw | gplus.to/phgaw A method of solution is perfect if we can forsee from the start, and even prove, that following that method we shall attain our aim.               -- Leibniz