Re: Documentation Improvement Proposal

On Tue, Aug 2, 2011 at 9:46 PM, Steve Klabnik <[e-mail]> wrot=
e:
>
>> 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?).

--=20
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.
=A0 =A0 =A0 =A0 =A0 =A0 =A0 -- Leibniz