> 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.
Excellent!
> 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?
Well, Matz is happy with it, and the Japanese developers who have had
their files documented have appeared to be grateful for the efforts taken.
There could of course be hugh rumblings of discontent below the surface,
but I hope not ;)
> 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?
It's not something I've ever seen discussed in any depth. Here are my
points of view:
- I do what I can, not what I can't
- Japanese rubyists are well served by a large number of
published books
- We can make life easier for speakers of other languages by
presenting good English documentation in a way that can be
translated fairly easily
Expanding that last point:
- One possibility for other languages would be to maintain skeleton
stdlib source files (class and method definitions, no code) with
different-language comments that can be RDoc'ed and incorporated
into the stdlib-doc project, making available for download one
huge tarball with documentation in lots of languages!
- Obviously there would be significant manual effort in maintaining
a different "source base", but it's a small amount of manual effort
compared with producing the English docs in the first place.
> I've got some vague thoughts about the above, and will give it some time
> over the next week or two.
That will be good.
> 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...
Cool, keep us posted.
> 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...
That would/will be a good thing, that's for sure.
> Cheers,
>
> Simon
Gavin
|
