Re: Numeric#coerce docs are a disaster

Hi,

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.
> 
> http://blog.rubybestpractices.com/posts/rklemme/019-Complete_Numeric_Class.html

When I read this and the response form Adam:

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.

it reminds me what I just wrote a few weeks ago, no real feedback at
all: http://www.ruby-forum.com/topic/2168384#1011502 .

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.

My problem with that approach and this here

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

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.

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.

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

- Markus