From: Steve Klabnik Date: 2011-08-03T04:46:34+09:00 Subject: Re: Documentation Improvement Proposal Apologies, I've just responded to everyone in-line. > As I mentioned, the focus for me right now isn't deciding about structure of organization etc. It is, as you've already stated getting content up. Totally. And please, don't take my words the wrong way; I care deeply about documentation, and I do think Ruby is deficient. I haven't done much personally on this yet, but that's largely because my latest contract is going to be up this week, and so side things have been pushed aside. I'm taking the next 6 months off, though, and this is something I'd like to help improve. > 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. > But if it's the > general any-user-controlled content aspect you don't like, then naturally I > can see your objections! :) 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. > Are you familiar enough with the Python Doc team/process to push us in the right direction? 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. > Since I'm more of a person to do things than make them pretty I'd appreciate help in such matters. > Yes, please provide feedback. 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. I'm making a note to send you an email about this sometime this week or early next. I was going to anyway, but since this has come up, I'll make sure to, now.