From: Markus Fischer <markus@...>
Date: 2011-07-19T07:36:11+09:00
Subject: Re: Ruby Readline - and why ruby can learn from python

Hi Marc,

I really had to smile benignly when I read your post.

On 18.07.2011 22:02, Marc Heiler wrote:
> I did search. I looked around a bit and indeed, there is elegant and
> nice documentation about Readline. For example, here:
> 
>   http://bogojoker.com/readline/

I compared this page with the official docs. I discovered content-wise
that the docs were pretty much matching except the completion part. I've
made a patch for the docs including these parts:

https://github.com/mfn/ruby/commit/ae1bea694d5ee1852cfce3c2c2b42155952bd900

When I generate the docs from it, it looks like this
http://i.imgur.com/e7U5G.png . Ugh. The headings don't suit well and the
source code has no highlighting (in case your wonder: that's FF 5 with
150% full-page zoom).

But some of the existing ones in this module don't look much better,
e.g. http://i.imgur.com/SZ2k9.png . Hmm.

Well, the problem as I see it is that tutorial-like examples, when you
have quite some of them, don't really fit well within a discrete method
documentation. It makes it hard for the developer to discover. IMHO all
the examples from Readline.readline and what I've added should be moved
out either into the README or into the Readline module description and
the actual method documentations should be made more slim. But who to
make a call for anything here?

> HOWEVER, please compare the python documentation about Readline:
[...]
> Even php allows at least user added hints on how to best use this!

I've been actively following PHP community a few years ago. I don't know
much about the python community, but my impression is that the # of
contributors to the project, documentation wise, is like this:

PHP > ruby

I.e. the PHP community has a *lot* of driving force behind the
documentation team. Just compare http://marc.info/?l=phpdoc with
http://news.gmane.org/gmane.comp.lang.ruby.documentation (ruby-doc: 3
messages in July, with one unsubscription -> PHP: 70 (!) and counting.

Another thing I noticed: a lot of times it looked to me that most ruby
developers use method-centric approach to document things in the
ruby-world which, as I reasoned above, doesn't suit well for fluent
readable documentation (but maybe I looked at the wrong docs).

I know that PHP has quite a different approach, using docbook and only
parsing the prototype information from the sources, matching with
docbook and doing everything else there. But the reason mustn't be
necessarily docbook; it's how they approach to write the documentation.

I took the time and integrated the example because "I've been there done
that": in the open source world, I've not seen often coming something
practically out of a complaint ;-) [don't take that tooseriously, I'm
not criticizing your for your post; by doing that patch I provided
evidence for a counter-example anyway]

- Markus