Re: Numeric#coerce docs are a disaster

On Aug 2, 2011, at 7:30 AM, Markus Fischer wrote:
> On 02.08.2011 14:55, Robert Klemme wrote:
>> On Tue, Aug 2, 2011 at 12:40 PM, 7stud -- <[e-mail]> =
wrote:
>>> 1) I don't know how coerce works.
>>=20
>> =
http://blog.rubybestpractices.com/posts/rklemme/019-Complete_Numeric_Class=
.html
>=20
> When I read this and the response form Adam:
>=20
> On 02.08.2011 12:32, Adam Prescott wrote:
>> You are free to improve the documentation and open a ticket on =
redmine
>> assigned to Eric Hodel.
>=20
> it reminds me what I just wrote a few weeks ago, no real feedback at
> all: http://www.ruby-forum.com/topic/2168384#1011502 .

Since you posted it to ruby-talk and not to ruby-core (or a ticket) I =
missed it.  In brief, if you think it can be better, file a ticket.

The reason I say "file a ticket" is because I will forget if we only =
talk about it here.  I'm very busy with both work and preparing for the =
Ruby 1.9.3 release so I probably won't have free time available to work =
on these things for a while now.

=46rom your post:

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

If you think the organization of something is poor then file a ticket =
proposing a reorganization.  I agree that it's easier to read when some =
examples are moved up to the top level.

Take a look at the documentation of Net::HTTP or OpenSSL in Ruby =
1.9.3-preview1.  They've been reorganized and improved to show you the =
various ways you can use the two libraries in one place with slimmer =
documentation on individual methods.  I think this is a vast improvement =
over hunting through the 10 or 15 methods you may need to call to get a =
working program, and I think Readline would benefit from a similar =
reorganization.

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


If you think the RDoc HTML output can be better then file a ticket or =
write a new template or generator.  The current default generator, =
Darfkish, was contributed by Michael Granger.  HTML and web browsers =
have advanced quite a bit since it was included so if something nicer is =
built it can be added to RDoc and be made the default.

> If it were me, I'd bow before Robert for doing this great work, ask =
for
> his permission and simply stuff all his wisdom into the docs and let =
the
> world joy on it.

Done!

> My problem with that approach and this here
>=20
> On 02.08.2011 13:26, Adam Prescott wrote:
>> =
http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge
>> =
http://blog.steveklabnik.com/2011/05/10/contributing-to-ruby-s-documentati=
on.html
>=20
> is the following: Roberts post includes a and much more widened =
example
> and I'd be all for including it, but it doesn't fit will with how =
rdocs
> are most commonly used currently, that is, one page for all methods. =
If
> documentation for methods becomes to long as I outlined, things get
> noticeably unreadable.
>=20
> I've no further solution, but somehow it strikes me that the whole =
ruby
> documentation misses the next evolutionary step, away from the docs =
only
> generated from the sources to a) possible include much more meta
> documentation (manuals, tutorials, etc.) and b) provide *a*/*the*
> *official* ruby docs, not just class based docs, but also including
> introductory articles etc., e.g. from the existing ruby wikibook and =
so
> on, allowing comments on the docs as others mentioned and what not =
features.

Ruby still needs more of two types of documentation, the manuals, =
tutorials, etc. and the class and method-level documentation of the =
standard library.  Through the efforts of my documentation challenge the =
latter has grown to having =E2=85=94 of the standard library documented =
for Ruby 1.9.3 out of about 15,000 items.  I don't know of anybody =
addressing the former beyond these recent discussion and what's present =
at ruby-doc.org.

> But unfortunately it's lacking a power behind, a group of volunteers =
a)
> providing the technical environment and b) writers. When I look at =
other
> projects, e.g. PHP, the doc team not only provides infrastructure and
> assistance, they're also permanently communicating with the core
> developers to properly document new things for a release, properly
> describe backward compatibility problems (I mean, just look at the =
list
> at http://www.php.net/manual/en/ ).

I became a Ruby committer through submitting documentation patches, and =
anyone can become a committer the same way.  I did a decent job of =
committing documentation patches in a timely manner, but it would be =
great if I could have some extra help.  I don't see any reason why =
people couldn't be both.

> I wish I'd the skills for either forming a basis or writing good docs,
> unfortunately I'm quite un-gifted for the latter (I still try to =
improve
> it and contribute) and I seriously lack ruby-foo or whatnot for the =
former.

For the documentation challenge, writing good documentation was =
most-preferred, but I applied even "poor" documentation patches after =
appropriate editing or expansion.  For every patch I wasn't able to =
directly apply I provided feedback to the submitter.  In total, I think =
only two patches weren't applied out of between 40 and 50, one that =
duplicated an earlier submission and one being a mistaken typo fix about =
the math meaning of a number range like "[0, 1)".

For class and method-level documentation even poor documentation can be =
edited or expanded into something good!  Through feedback even you can =
write good documentation!  Please do not be afraid of rejection, I try =
very hard to avoid rejecting documentation patches.=