Hi Mark/Gavin,
Thanks a heap for your responses. I now see where Ruby docs are and
where things are heading. I feel pretty positive about all the current
ideas, and would be glad to help where I can.
It does initially seem a little unfair that docs in the source will be
in English. Maybe not *too* unreasonable as method-names and variables
will be in English anyway [some common convention is needed]. I presume
that the Japanese developers are happy with this approach?
Have any ideas about making documentation more "even-handed" with
respect to language been debated? Or mechanisms for knowing which
Japanese/korean/french/spanish/whichever documentation needs to be
updated, other than looking at the changelogs for every file? Or how to
deal with the fact that developers not fluent in English are likely to
skip updating the RDoc in the source file when changes are made? Or
maybe update a version in some language other than English (the
translation) directly, leaving the "master" English version out-of-date?
I've got some vague thoughts about the above, and will give it some time
over the next week or two.
The next few weeks are likely to be very busy ones for me (including
moving house this w/end) but I would definitely like to be involved in
working on Ruby's docs. And I might write that overview of Shell (at a
higher level than Takashi's existing overview) after all...
I guess that once the "doc" project gets a reasonable body of docs done,
it can earn itself a place in the major "ruby documentation" link at
ruby-lang, which will then help people (like me) find it. The first step
is always the hardest one...
Cheers,
Simon
|
