On Aug 2, 2011, at 7:30 AM, Markus F. wrote:
assigned to Eric H…
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 G… 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!
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.
