Re: Documentation of kernel messages (Summary)

[Li Yang]

On Wed, 2007-07-11 at 00:12 +0800, Rob Landley wrote:
> On Monday 09 July 2007 13:18:57 Gerrit Huizenga wrote: 
> > On Mon, 09 Jul 2007 12:48:24 EDT, Rob Landley wrote: 
> > > In regard to translating kernel messages: 
> > > 
> > > On Monday 09 July 2007 01:36:31 H. Peter Anvin wrote: 
> > > > Kunai, Takashi wrote: 
> > > > > (1) Your kernel development proposal will be greatly supported
> by 
> > > > > Japanese vendor community. At the same time, it needs support
> from 
> > > > > the kernel communities, as well. 
> > > > 
> > > > There is a very strong reason for the kernel community to NOT
> support 
> > > > this: it makes it much harder to deal with bug reports. 
> > > 
> > > Agreed. 
> > 
> > [...] 
> > 
> > > As for the documentation translations themselves, I note that
> Eric 
> > > Raymond dissuaded me from actually hosting translations of kernel 
> > > documentation on http://kernel.org/doc due to his experience with 
> > > translations of his own writings.  If he hosts the translations on
> his 
> > > website, they never get updated again.  But if he makes the
> contributor 
> > > host them on their own website, then they sometimes get updated. 
> > > 
> > > For my part, I can't _tell_ when a given translation is out of
> date 
> > > because I can't read it, and I certainly can't update it.  So I
> agree 
> > > with Eric and I'm linking to sites hosting kernel documentation in
> other 
> > > languages rather than hosting them myself.  I've got a good link
> to a 
> > > Japanese site, need to ping the contributors of the chinese
> documentation 
> > > and see if they have a site for it... 
> > 
> > Yeah, but it seems like having a translations directory in the
> kernel 
> > avoids that problem - anyone can update, it is a single source, no
> digging 
> > for sites that aren't tied to the kernel, available in the distros 
> > directly, etc.
> 
> No.  It doesn't help.
> 
> 99% of the kernel directory is C.  That means any random passerby can
> review 
> code.  Everyone who has the kernel tarball should be able to review
> code 
> that's in there, plus when you compile it breaks.  So merging _code_
> into the 
> kernel helps keep it up to date.
> 
> Merging documentation into the kernel doesn't help keep it up to date,
> because 
> documentation being out of date doesn't break the build.  It may get
> the 
> documentation more review, but the existing state of Documentation/*
> argues 
> against that.  It's a struggle to keep the english versions on the
> same 
> continent as "up to date" or "complete", and most of the _good_
> documentation 
> is out in OLS papers and such (which I'm off indexing as we speak).
> 
> Now add in the non-english nature of the new Documentation/stale 
> subdirectories you're proposing.  Almost nobody in the existing
> kernel 
> community can even _read_ this documentation, let alone update it.
> People 
> who update Documentation/* _can't_ update the translations, and that
> will 
> _never_change_.

There are quite a lot kernel developers for each of the popular
language, AFAIK.  For non-popular languages, there shouldn't be
translation available in the first place.  It was really a surprise when
I post my Chinese translation on the LKML so many Chinese speakers have
commented on the translation and encouraged the translation work.  They
are not visible as they usually don't talk too much.  :) So I set up the
Chinese kernel development maillist(linux-kernel@xxxxxxxxxxxxx), there
will be more and more experienced kernel developer who can read and
update the Chinese documents after they read the translated
documentation and become kernel hacker.

> 
> Merging into the kernel is a great way to keep CODE up to date.  Don't
> think 
> it's magic pixie dust for documentation.  It never has been before.

IMHO, having contribution merged into the kernel has the MAGIC to
attract people to work for recognition.  When more and more people
volunteer to work on it, the documentation will be up to date magically.

> 
> > I'm not sure that the web site hosting argument is a good one.
> Arch 
> > maintainers and Language Maintainers have some similarities.
> 
> Ah, but It's not a language maintainer's job to update documentation.
> It's 
> their job to ACCEPT PATCHES.  Translate patches, translate questions
> back and 
> forth.  This has NOTHING to do with documentation unless they're
> converting 
> documentation accompanying the patch one way; into english.

Language maintainers can integrate updates to the documentation just
like integrating any updates to the code.  Working on the documentation
is ,IMHO, a perfect task for novice kernel hacker to get familiar with
the process.

> 
> > Also, being 
> > able to clearly mark which version of a document was last
> translated 
> > would help a bit with the fact that most of us aren't proficient in
> all 
> > of the world's languages.
> 
> Keeping translations up to date is not something I can do, and thus
> not my 
> problem.
> 
> > But, knowing who the translation maintainer is, 
> > and when the translation was last updated allows both the original
> doc 
> > maintainer and the translation document maintainer to see when a
> document 
> > likely needs to be updated.  And that is probably good enough.
> 
> Thank you.  You've just scared away all potential language maintainers
> by 
> making them think we want them to translate all the world's existing 
> documentation.  Do you know how long it takes just to read through
> the 
> existing Documentation directory?  (Have you done it?)
> 
> When I'm talking about language maintainers I am NOT looking for them
> to 
> translate existing documentation or keep Documentation/* up to date
> for some 
> other langauge.  That's a more than full-time job.  I've been looking
> around 
> for weeks for someone to just accept Japanese patches, and everybody
> I've 
> talked to says it's too much time commitment without any extra work
> piled on 
> top of it in by armchair commentators who won't be _doing_ that work.

It won't be too hard if the work is shared by a community.  Like the one
I'm trying to establish.

- Leo

Advertisement time:
Chinese kernel development community http://zh-kernel.org    :)



-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/