Documentation Improvement Proposal

Ruby
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 W.
Twitter: http://www.twitter.com/cwgem

[1]RDoc Documentation
[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]GitHub - cwgem/RubyJaReferenceManualTranslation: A translation of the Japanese Ruby Reference Manual at http://doc.ruby-lang.org/ja/1.9.2/

2

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.

3

On Tue, Aug 2, 2011 at 6:36 PM, Chris W. [email protected] wrote:

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

–
Phillip G.

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

4

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.

5

On Tue, Aug 2, 2011 at 7:39 PM, Steve K. [email protected]
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.

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:

–
Phillip G.

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

6

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

Ruby has absolutely nothing like the Python Doc team. Or at least, if
we do, they’re not doing their job.

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 W.
http://www.twitter.com/cwgem

7

On Tue, Aug 2, 2011 at 7:00 PM, Steve K.
[email protected]wrote:

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

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.

8

On Aug 2, 2011, at 11:00 , Steve K. wrote:

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:

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

9

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

On Aug 2, 2011, at 11:00 , Steve K. wrote:

[]

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.

10

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.

11

On Tue, Aug 2, 2011 at 9:46 PM, Steve K. [email protected]
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 G.

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

12

On Tue, Aug 2, 2011 at 8:46 PM, Steve K.
[email protected]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.

13

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-

14

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

>________________________________
>From: Phillip G. <[email protected]>
>To: ruby-talk ML <[email protected]>
>Sent: Tuesday, August 2, 2011 1:47 PM
>Subject: Re: Documentation Improvement Proposal
>
>On Tue, Aug 2, 2011 at 7:39 PM, Steve K.
<[email protected]> 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.
>
>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:
>
>–
>Phillip G.
>
>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
>
>
>
>

15

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.

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

…

16

On 02.08.2011 18:36, Chris W. wrote:

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

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
17

On Aug 2, 2011, at 12:46 , Steve K. wrote:

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.

18

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

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.

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

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

  2. discussion page for each page of documentation

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

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

19

I would like to touch on a more general issue I’ve had with language
docs of all kinds not limited to programming languages either. The
big issue I tend to have is that the documentation is essentially a
dictionary for various functions, the “how” portion or the grammar is
usually located in a separate book or document which makes it more
difficult to put things together. It would be wonderful if any
refresh to Ruby’s documentation made a concerted effort to make sure
that it is simple to cross-reference the grammar with method
definitions and other example elements. Right now documentation
across the board (Not just Ruby’s.) in my experience seems to be a
list of definitions and not much else. Imagine trying to learn a
second language by just reading a dictionary and not being told about
how to structure nouns, verbs, etc. Or more accurately imagine
learning them separately.

It isn’t enough to have good code samples, the samples have to be
integrated with the rest of the language as a whole, integration has
to be pervasive. If a function G in example 2010232 takes a block as
an argument a user on the doc site should be able to select that
argument and find out more about what a block is in Ruby. Preferably
in a way that doesn’t take the user away from the code they started
out looking at.

20

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

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:[email protected]?body=help

So you email the address with help and get:

               Get multiple files (ML articles or archive files)
  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