Documentation Improvement Proposal

ruby-talk
1

= Issues =

The motivation for writing most of this email is the documentation threads I've noticed pop up now and then in -talk, as well as a number of underlying factors. As I see the current state of Ruby documentation:

First off, the official documentation is mainly constrained to automatically generated documentation taken from source code comments. This means that the online version of the documentation is full of frames and lacks in structure. The user is forced to sort through a giant list of classes with no way to discern one from the other. Compare this with the following (this is just a rough example):

Numeric

Integer
Bignum
Float
Math
...

Strings

String
Regexp
MatchData

Object Storage

Struct
Hash
Array
..

Files and Directories

File
Dir
IO
...

Operating System

Process
Signal
Env
...

So if a user wants to study Ruby's handling of numeric types, they can easily narrow down on them. Those interested in systems program can focus on the Operating Systems category. Finally, it helps when a user who has no idea what class to look for by narrowing down the list of choices. From there the user can decide what class best suites their needs, and compare it to other similar classes.

Next is the language issue. Ruby is a programming language with roots in Japan. This means that a good amount of the core team speak Japanese as their main language, and I've noticed the Japanese documentation [2] to be a bit more thorough and better laid out. In fact there is already a project underway to improve the Japanese documentation[3]. However my fear is that the English documentation will become further out of sync.

As a final concern, both sets of documentation do not provide a way for the addition of user comments. This is a core feature of the PHP documentation that make it such a success. Users can point out weird edge cases or useful examples of how to utilize something that is not apparent by simply looking at the provided documentation.

This are just a few issues with much more that I could go into. Now with that all in mind I'd like to discuss a proposal for improving the state of the documentation.

= Steps Towards Improvement =

So are the steps I would like to take in order to improve the overall status:

* Find a hosting sponsor as an official documentation project will most likely generate a reasonable amount of traffic which would be too much of a financial burden for me to take on alone
* Establish a content management system / wiki which will allow for:
   * User comments
   * Multiple contributors ( content writers, translators, editors, etc. )
   * Multi-lingual support ( not just Japanese and English, but also allow for translations in multiple languages )
   * Revision support for rollbacks and ability to see revision history
   * Support for syntax highlighting
   * Ability to categorize / tag / adjust navigation
* I'll start putting up documentation, the idea being that I would like to have a good chunk of content up so everyone has something tangible to see
   * Most likely I'll start by doing a port of the Ruby Koans [4] to a more tutorial oriented format, as I like way the content is categorized
   * Continue my translation [5] of the Ruby Japanese documentation so that there is a reference of some type for parts of the language which are not classes
* Once this is done I will put out a call for contributors including:
    * Content writers
    * Editors
    * Translators ( while not essential at this phase, it would be nice to get it started early before the scale gets massive )
    * Site administrators / moderators ( For helping to moderate comments and make sure they're not spam or are off topic )
    * Anyone to add comments to help improve the general documentation
* Look at getting a project setup in redmine for people to file documentation bugs or any other issues that come up

I think this is enough to work with for now.

= Actionable Items =

While I would very much enjoy others to hop on and help out, I don't expect it at the "I have a dream" stage. However in the event that you do want to help out:

* It would be nice the Japanese reference manual translated to have something based off official documentation, so feel free to fork the GitHub repository or just send translations to me by email and I'll add them
* Providing hosting so I have something to put the content management system on
* Recommendations for the content management system
* Volunteers to help with writing a tutorial revolving around the Koans ( this can sit on GitHub until the content management system goes up )

= Conclusion =

That does it for this long email proposal. If you have any questions feel free to email at this address, respond to this thread or throw me a tweet on Twitter (@cwgem).

Regards,
Chris White
Twitter: http://www.twitter.com/cwgem

[1]http://ruby-doc.org/core/
[2]http://doc.ruby-lang.org/ja/1.9.2/doc/index.html
[3]http://redmine.ruby-lang.org/projects/rurema
[4]http://rubykoans.com/
[5]https://github.com/cwgem/RubyJaReferenceManualTranslation

2

[…]

So if a user wants to study Ruby's handling of numeric types, they can easily narrow down on them. Those interested in systems program can focus on the Operating Systems category. Finally, it helps when a user who has no idea what class to look for by narrowing down the list of choices. From there the user can decide what class best suites their needs, and compare it to other similar classes.

Your focus seems to be largely on the HTML documentation, but there's also ri. Why don't we take your proposed front matter and check it into ruby itself where both ri and any generated HTML can take advantage of it?

Well, I prefer doing it in markdown to avoid the clutter of tags, converting to HTML using a tool of some sort. As for the layout part, I wish I were more familiar with how the documentation is generated. I'd like to improve on the overall style, but the best I can provide is a sample template with HTML, CSS, and JS showing how I think it should like. If someone can offer me guidance on how to integrate that into the generation workflow that would be great.

Next is the language issue. Ruby is a programming language with roots in Japan. This means that a good amount of the core team speak Japanese as their main language, and I've noticed the Japanese documentation [2] to be a bit more thorough and better laid out. In fact there is already a project underway to improve the Japanese documentation[3]. However my fear is that the English documentation will become further out of sync.

The documentation from the core standard library is written in English, so I'm uncertain about what will become out of sync between the two. I think you're writing the wrong mailing list though, you should contact the rurema people to have your concerns addressed.

The out of sync part is I don't see where there's an easy to spot place on the documentation page that details the core syntax and details such as field input separators, blocks, yield, etc. It's the core API classes and the standard library, please a few links to books and what not, but those can become out of date. Take for example:

http://doc.ruby-lang.org/ja/1.9.2/doc/spec=2fcall.html

This is Japanese documentation explaining a few things such as yield and block arguments.

As a final concern, both sets of documentation do not provide a way for the addition of user comments. This is a core feature of the PHP documentation that make it such a success. Users can point out weird edge cases or useful examples of how to utilize something that is not apparent by simply looking at the provided documentation.

Having user contributions only on a website seems like a waste of community effort. 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.

That's why I was suggestion moderation, it would help ensure that questions more suitable for -talk or IRC would not leak in. My general concern is that there would be interesting use cases which are not applicable to the average user. However after careful consideration I think these can be added as "articles" or put in a specific location for advanced use materials.

This are just a few issues with much more that I could go into. Now with that all in mind I'd like to discuss a proposal for improving the state of the documentation.

= Steps Towards Improvement =

So are the steps I would like to take in order to improve the overall status:

* Find a hosting sponsor as an official documentation project will most likely generate a reasonable amount of traffic which would be too much of a financial burden for me to take on alone

James Britt is the current maintainer of ruby-doc.org, you can contact him from his email address in the sidebar.

Okay I will give James a shout out.

* Establish a content management system / wiki which will allow for:
* User comments
* Multiple contributors ( content writers, translators, editors, etc. )
* Multi-lingual support ( not just Japanese and English, but also allow for translations in multiple languages )

I suggest you get in touch with the rurema people before attempting to build something they don't want and won't use. When I spoke to okkez at RubyKaigi about combining efforts I got the idea that this is not one of their goals and that they wouldn't want to use such a tool. It may have been due to my lack of proper understanding though.

I will have to get in touch with them then. Just need to find the proper place to do so (some kind of chief contact that understands the project direction as a whole).

* Revision support for rollbacks and ability to see revision history
* Support for syntax highlighting
* Ability to categorize / tag / adjust navigation
* I'll start putting up documentation, the idea being that I would like to have a good chunk of content up so everyone has something tangible to see
* Most likely I'll start by doing a port of the Ruby Koans [4] to a more tutorial oriented format, as I like way the content is categorized
* Continue my translation [5] of the Ruby Japanese documentation so that there is a reference of some type for parts of the language which are not classes
* Once this is done I will put out a call for contributors including:
  * Content writers
  * Editors
  * Translators ( while not essential at this phase, it would be nice to get it started early before the scale gets massive )
  * Site administrators / moderators ( For helping to moderate comments and make sure they're not spam or are off topic )
  * Anyone to add comments to help improve the general documentation

My recommendation is to stop proposing, stop asking and start doing.

I've already stated what I plan to do, it was more to get it out in the open and get people starting to talk about it. Consider it more of "Hey guys here's what I'm going to do" than a "What do you think about this?" Though I'm already getting back great feedback.

I didn't ask if people wanted to contribute documentation to Ruby 1.9.3, I challenged them and gave them easy guidelines for contributing. Then I wrote a bunch of documentation myself.

As I stated, work is already underway to translate the syntax portion of the JP docs (in fact I was working on it not even 10 minutes ago). Also I plan tonight/tomorrow to start putting the Koans into a tutorial style format. Yes, I totally plan to write a bunch of documentation.

Through the challenge, documentation was increased from 54% to 65% and most of that increase came from outside contributors.

See: http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge

Similarly, rubygems.org was written by Nick Quaranto without asking for permission. He simply did it and now we have an awesome site for hosting gems.

I'd still like to avoid duplicated effort between rurema, any improvements made to ruby-doc.org or a replacement of ruby-doc.org, it may be easier to build by simply fulfilling the needs you see are unmet.

As I mentioned I'll reach out to them (though I'll have to use formal Japanese, so it will take same time to write up). Partly because I'm curious of how the existing layout is built (static pages only, etc.).

* Look at getting a project setup in redmine for people to file documentation bugs or any other issues that come up

It's easy! We don't need a new process for this!

You create a patch and attach it to a ticket in redmine in the DOC category. You can even assign it to me for faster commit.

All right. I'll try and work out a patch a week to start out, then increase pace if it feels too slow. Mainly I want to get the content that doesn't exist yet up.

You can also create a pull request on github but that may take longer to be applied.

I think this is enough to work with for now.

Please, just do it, but if you add user comments please make it easy to fold them back into the source and remove them from the website. If I were a PHP committer and found myself encountering a page like this I would be embarrassed at my failure to incorporate useful contributions by users: PHP: openssl_sign - Manual

(Fortunately I wrote OpenSSL documentation for Ruby that contains examples similar to those provided in the user comments of the PHP site. You can see it in Ruby 1.9.3-preview1 if you `ri OpenSSL`.)

That I will. Expect to hear from me soon :slight_smile:

Best Regards,
Chris White
Twitter: http://www.twitter.com/cwgem

···

On Aug 2, 2011, at 11:54 AM, Eric Hodel wrote:

On Aug 2, 2011, at 9:36 AM, Chris White wrote:

3

I reeeeeealy dislike user comments on documentation. It's one of the
worst thing about PHP's documentation.

That said, if any of you follow me on Twitter, you'll have seen the
zillions of tweets I sent out today about this; I _do_ think that
Ruby's documentation needs a lot of work. I'm not sure that a huge,
heavy-handed process is the right way, though.

4

* Recommendations for the content management system

Given your requirements, TikiWiki[0] would fit quite well, and allows
for quite a bit more (From issue tracking, to automagically generating
a book-like PDF, multilanguage support and tagging are baked in and it
provides publishing stages [writing, editing, publishing], as well as
comments).

The downside is that it requires a relatively beefy host (Loads of
memory for PHP, and a long running time for the scripts).

Otherwise, DokuWiki[1] isn't resource hungry, and operates on plain
text files, which, when using the markdown plugin, should allow
transformation into other formats via pandoc[2] that can be printed
easier or read on a mobile reader when internet access isn't
available.

If RDoc generation is a hard requirement, pandoc can also be fed plain
old HTML and transform that into PDF, ePUB, &c. if multiple formats
are desired.

* Volunteers to help with writing a tutorial revolving around the Koans
( this can sit on GitHub until the content management system goes up )

While not based off of the RubyKoans, feel free to steal my AES crypto
tutorial from [3] for a tutorial section on Ruby, or to inspire a
RubyKoan or two.

[0] http://info.tiki.org/Tiki+Wiki+CMS+Groupware
[1] dokuwiki [DokuWiki]
[2] Pandoc - index
[3] Learn How to Blog and Build Websites for Profit!

···

On Tue, Aug 2, 2011 at 6:36 PM, Chris White <cwprogram@live.com> wrote:

--
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

5

So if a user wants to study Ruby's handling of numeric types, they can easily narrow down on them. Those interested in systems program can focus on the Operating Systems category. Finally, it helps when a user who has no idea what class to look for by narrowing down the list of choices. From there the user can decide what class best suites their needs, and compare it to other similar classes.

Strongly agree, and I even proposed something similar recently to
ruby-core, where it was basically greeted by crickets LOL.
I'd be happy to help out.

The beginnings of my attempt at it were at fleshing out parts of the
Ruby WikiBook:
http://en.wikibooks.org/wiki/Ruby_Programming

Thanks!
-roger-

6

The only objection I've is that I'm not sure if it is really suited well
for multiple versions of Ruby. I.e. the docs written would have to be
associated for a specific version otherwise things can become very
confusing. If you look at http://www.ruby-doc.org/ you see multiple
standard libraries referenced by their version number.

I'd be interesting how to solve this with a typical cms/wiki software.
Basically, the documentation would have to tied to a specific ruby
version and naturally migrate with it's evolution (i.e. new relases, etc.).

What I want to say: if you have the new doc system as source files (XML,
rdoc, whatever), you naturally version them and can branch them and thus
it's possible to have this documentation <> ruby version link; you even
can backport documentation improvements and such. I'm unsure if that
would be possible with a classical online CMS/wiki.

sincerely,
- Markus

···

On 02.08.2011 18:36, Chris White wrote:

* Establish a content management system / wiki which will allow for:

7

What's wrong with stealing WikiPedia's procedures? The model works
quite well, even for narrower topics (Like Memory Alpha, the Fallout
Wiki, and the Portland Pattern Repository show).

Don't mistake a centralised approach with a heavy handed, monolithic,
cathedral-style process. :slight_smile:

···

On Tue, Aug 2, 2011 at 7:39 PM, Steve Klabnik <steve@steveklabnik.com> wrote:

That said, if any of you follow me on Twitter, you'll have seen the
zillions of tweets I sent out today about this; I _do_ think that
Ruby's documentation needs a lot of work. I'm not sure that a huge,
heavy-handed process is the right way, though.

--
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

8

What's wrong with stealing WikiPedia's procedures? The model works
quite well, even for narrower topics (Like Memory Alpha, the Fallout
Wiki, and the Portland Pattern Repository show).

Oh, man, if Ruby documentation ever becomes like Wikipedia, please,
shoot me now.

What I mean is this: right now, we barely have anyone actually
contributing documentation. Some people have stepped up since the doc
drive, and we get random patches from various people sometimes, but
Ruby has absolutely nothing like the Python Doc team. Or at least, if
we do, they're not doing their job.

9

Hello,
I have been out of so to speak developing for a little while and go interested in Ruby. So, I am picking it up. With that I have a bit of a different view and that is of someone who would live to see some good documentation and APIs. So with that I took a look at some languages I have used int he past Python, PHP, Java and found that PHP was pretty darn good next would be Python as it was similar to PHP. Javadoc is OK, but for someone new it is very daunting. As far as user input for the documentation; if set up correctly I see no issue. Example that I did just yesterday.

ary = Array.new(r, Array.new(10))
vs
ary = Array.new(10) { Array.new(10) }

Seemingly the same, but they are not. User documentation might say the best way to do multi-dimensional array. Note I am learning and tried the first as I found that Array.new(some initial size, some initial value) was the basic Array API.

Anyway, this is my two cents.

···

--
Joshua Vaughn

&gt;________________________________
&gt;From: Phillip Gawlowski &lt;cmdjackryan@gmail.com&gt;
&gt;To: ruby-talk ML &lt;ruby-talk@ruby-lang.org&gt;
&gt;Sent: Tuesday, August 2, 2011 1:47 PM
&gt;Subject: Re: Documentation Improvement Proposal
&gt;
&gt;On Tue, Aug 2, 2011 at 7:39 PM, Steve Klabnik &lt;steve@steveklabnik.com&gt; wrote:
&gt;&gt;
&gt;&gt; That said, if any of you follow me on Twitter, you&#39;ll have seen the
&gt;&gt; zillions of tweets I sent out today about this; I _do_ think that
&gt;&gt; Ruby&#39;s documentation needs a lot of work. I&#39;m not sure that a huge,
&gt;&gt; heavy-handed process is the right way, though.
&gt;
&gt;What&#39;s wrong with stealing WikiPedia&#39;s procedures? The model works
&gt;quite well, even for narrower topics (Like Memory Alpha, the Fallout
&gt;Wiki, and the Portland Pattern Repository show).
&gt;
&gt;Don&#39;t mistake a centralised approach with a heavy handed, monolithic,
&gt;cathedral-style process. :slight_smile:
&gt;
&gt;--
&gt;Phillip Gawlowski
&gt;
&gt;phgaw.posterous.com | twitter.com/phgaw | gplus.to/phgaw
&gt;
&gt;A method of solution is perfect if we can forsee from the start,
&gt;and even prove, that following that method we shall attain our aim.
&gt; -- Leibniz
&gt;
&gt;
&gt;
&gt;

10

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. This is a responsibility I plan to take on as the submitter of this proposal. I'm already evaluating different systems to use, an reaching out to people for possible hosting sponsorship. I don't expect anyone to sign on at this point, as there's nothing tangible for you to evaluate. My hope is to get enough content up so that even if I do drop off the face of the community, the next willing and able person won't have to start from scratch. I leave it to you on how much faith you wish to put in that.

Regards,
Chris White
http://www.twitter.com/cwgem

···

On Aug 2, 2011, at 11:00 AM, Steve Klabnik wrote:

What's wrong with stealing WikiPedia's procedures? The model works
quite well, even for narrower topics (Like Memory Alpha, the Fallout
Wiki, and the Portland Pattern Repository show).

Oh, man, if Ruby documentation ever becomes like Wikipedia, please,
shoot me now.

What I mean is this: right now, we barely have anyone actually
contributing documentation. Some people have stepped up since the doc
drive, and we get random patches from various people sometimes, but
Ruby has absolutely nothing like the Python Doc team. Or at least, if
we do, they're not doing their job.

11

Do you mean in appearance or approach to openness?

I think the general wiki setup is quite good for focused topics, as Phillip
mentioned. Memory Alpha is reliable in its information, for instance, and I
think pages containing examples of code and an overall demonstration of Ruby
would be largely self-evident, which would get away from the problems
Wikipedia in particular has with regard to uncited material. But if it's the
general any-user-controlled content aspect you don't like, then naturally I
can see your objections! :slight_smile:

That said, I think the conventional structure of a wiki would lead to heavy
fragmentation.

What about Wikibooks or Wikiversity? I've seen Ruby material on those sites,
but they seem fall behind through lack of maintainers.

···

On Tue, Aug 2, 2011 at 7:00 PM, Steve Klabnik <steve@steveklabnik.com>wrote:

Oh, man, if Ruby documentation ever becomes like Wikipedia, please,
shoot me now.

12

Yeah... our Ruby Doc team is Eric. :slight_smile:

Are you familiar enough with the Python Doc team/process to push us in the right direction?

···

On Aug 2, 2011, at 11:00 , Steve Klabnik wrote:

What's wrong with stealing WikiPedia's procedures? The model works
quite well, even for narrower topics (Like Memory Alpha, the Fallout
Wiki, and the Portland Pattern Repository show).

Oh, man, if Ruby documentation ever becomes like Wikipedia, please,
shoot me now.

What I mean is this: right now, we barely have anyone actually
contributing documentation. Some people have stepped up since the doc
drive, and we get random patches from various people sometimes, but
Ruby has absolutely nothing like the Python Doc team. Or at least, if
we do, they're not doing their job.

13

It does say how to do it:

% ri Array
...
       # only one copy of the object is created
       a = Array.new(2, Hash.new)
       a[0]['cat'] = 'feline'
       a
       a[1]['cat'] = 'Felix'
       a

       # here multiple copies are created
       a = Array.new(2) { Hash.new }
       a[0]['cat'] = 'feline'
       a
...

···

On Aug 2, 2011, at 13:10 , Josh Vaughn wrote:

Example that I did just yesterday.

ary = Array.new(r, Array.new(10))
vs
ary = Array.new(10) { Array.new(10) }

Seemingly the same, but they are not. User documentation might say the best way to do multi-dimensional array. Note I am learning and tried the first as I found that Array.new(some initial size, some initial value) was the basic Array API.

14

[…]

Right now, we barely have anyone actually contributing documentation. Some people have stepped up since the doc drive, and we get random patches from various people sometimes, but Ruby has absolutely nothing like the Python Doc team. Or at least, if we do, they're not doing their job.

Yeah... our Ruby Doc team is Eric. :slight_smile:

Yup… pretty much I'm the doc team.

I'll commit just about anything anybody submits per http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge but I may need to edit it or assign it to a proper maintainer to get a detail right.

Are you familiar enough with the Python Doc team/process to push us in the right direction?

Yes, please provide feedback. For example, there's the documentation coverage report which is pretty ugly but functional:

http://segment7.net/projects/ruby/documentation_coverage.txt

But the challenge and the report are about all the help and tooling I've provided to get people involved.

Since I'm more of a person to do things than make them pretty I'd appreciate help in such matters.

···

On Aug 2, 2011, at 11:37 AM, Ryan Davis wrote:

On Aug 2, 2011, at 11:00 , Steve Klabnik wrote:

15

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! :slight_smile:

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.

16

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?).

···

On Tue, Aug 2, 2011 at 9:46 PM, Steve Klabnik <steve@steveklabnik.com> wrote:

--
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

17

Agreed. I think it's worth sacrificing the "total" (bearing the bureaucracy
of Wikipedia in mind) freedom to edit, in exchange for a greater quality in
the material, which will more than likely come about from someone curating
aggressively.

···

On Tue, Aug 2, 2011 at 8:46 PM, Steve Klabnik <steve@steveklabnik.com>wrote:

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.

18

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 suspect that they have a better time at it because they're not also dealing with a language barrier for the stuff that exists. Now that Eric has taken the baton, commits are being made much much faster and I suspect will accelerate slowly over time (the better the doco is, the easier it is to read, the easier it is to improve).

I would love to know more about the pydoco group and see if we can't adopt any of their practices where it makes sense.

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 dunno about now, but back when I was doing perl, python, java, etc... it was _all_ API doco and the rest was books. I'm not using that as an excuse. I'm just trying to set the bar at a rational level.

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.

appreciated.

···

On Aug 2, 2011, at 12:46 , Steve Klabnik wrote:

19

I'd like to see things broken up into four parts, actually, to take a
somewhat collaborative approach.

0. issue tracker page, where people ask for stuff and make notes about
things that need to be done

1. discussion page for each page of documentation

2. development page for each page of documentation, handled a bit like a
version control system -- drawing on stuff in the discussion page

3. "official" page, which is a curated version of what arises in the
development page

Make *all* of them publicly accessible, with varying levels of editing
access control (where only an "official" team has editing access to the
"official" page, of course, all the way down to general, free public
access to report things to the issue tracker).

It's possible the issue tracker and discussion could somehow be rolled
together into one thing.

···

On Wed, Aug 03, 2011 at 05:22:32AM +0900, Adam Prescott wrote:

On Tue, Aug 2, 2011 at 8:46 PM, Steve Klabnik <steve@steveklabnik.com>wrote:

> 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.
>

Agreed. I think it's worth sacrificing the "total" (bearing the bureaucracy
of Wikipedia in mind) freedom to edit, in exchange for a greater quality in
the material, which will more than likely come about from someone curating
aggressively.

--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

20

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?).

In your headers:

List-Help: <mailto:ruby-talk-ctl@ruby-lang.org?body=help>

So you email the address with help and get:

3.5 How to retrieve past articles

# index Get a list of files which you can # get
                   Index file will be returned if it exists

# get ID
# send ID Get a ML article (sends back in plain text)

# mget <range list> [mode] [interval]
# mget <regular expression> [mode] [interval]
                   Get multiple files (ML articles or archive files)
    Arg:
      <range list> Ex. 1-10,12,15-100 1,2,10
                        first first:10 last:30 100-last (MH syntax)
      <regular exp> Ex. * ? 1? 1??
      [mode] gz tgz rfc934 b rfc1153 d unpack uf (default=tgz)
      [interval] mail time interval if the reply spans multiple mails
                    (default=300)
    Mode:
     (No option) 'tar+gzip' -> spool.tar.gz
      tgz 'tar+gzip' -> spool.tar.gz
      uf PLAINTEXT(with UNIX From:)
      gz GZIP(with UNIX From:)
      rfc934 RFC934 format PLAINTEXT
      unpack PLAINTEXT(with UNIX From:)
      uu UUENCODE
      d RFC1153 format PLAINTEXT
      rfc1153 RFC1153 format PLAINTEXT

You can figure out the range from the archives:

http://blade.nagaokaut.ac.jp/ruby/ruby-talk/index.shtml

Remember, mail ruby-talk-ctl, not ruby-talk

···

On Aug 2, 2011, at 1:10 PM, Phillip Gawlowski wrote: