From: Eric Hodel Date: 2011-08-03T04:55:07+09:00 Subject: 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 -- 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 . 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. From 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 > > 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. 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 ⅔ 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.