From: Markus Fischer Date: 2011-08-02T23:30:57+09:00 Subject: 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 -- 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