Re: Documentation of kernel messages (Summary)

[Rob Landley <rob@landley.net>]

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_.

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.

> 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.

> 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.

> gerrit

Rob
-- 
"One of my most productive days was throwing away 1000 lines of code."
  - Ken Thompson.
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/