Re: Documentation of kernel messages (Summary)

[Rob Landley <rob@landley.net>]

On Thursday 12 July 2007 10:54:46 pm Tsugikazu Shibata wrote:
> On Thu, 12 Jul 2007 13:35:54 -0400, rob wrote:
> > On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote:
> > > > Fielding patches and questions sounds like plenty to me...)
> > >
> > > I do think the documentation translation is very necessary even when
> > > there is a language maintainer, especially for the policy documents as
> > > HOWTO, codestyle , and etc.  The contributors should go through these
> > > policies and check their code for compliance before going to the
> > > language maintainer for help, or there will be too much for the
> > > language maintainer to translate.  The language maintainer doesn't need
> > > to translate all the documents himself, but he can help to coordinate
> > > the translation effort and help to make it update to date.
> >
> > It would help if all the policy documents got grouped into a single
> > Documentation/development directory so we could separate "policy
> > documents in each language would be nice" from "that document about the
> > amiga zorro bus really needs to be kept up-to-date in Navajo and that
> > should be in the kernel tarball please".
> >
> > Lemme see, which ones are we talking about?  The candidates are:
> >   applying-patches.txt
> >   BUG-HUNTING
> >   Changes
> >   CodingStyle
> >   debugging-modules.txt
>
> This file seems mostly technical. may not policy related document.

Yeah, I guess so.  My mental filter was actually more like "how to do linux 
development", and it seemed both short and easy to translate, and also 
generally relevant to the majority of developers no matter what subsystem 
they're working on.

But I agree, it's not policy.

> >   feature-removal-schedule.txt
> >   HOWTO
> >   kernel-docs.txt
> >   language-maintainers.txt
> >   ManagementStyle
> >   oops-tracing.txt
> >   SecurityBugs
> >   sparse.txt

That one's not policy either, but it is general non-subsystem-specific 
development.  Probably "applying-patches.txt" above goes in the same bucket.

Whether or not to include that bucket in the new directory depends on whether 
the directory is labeled "development" or "policy" or something else...

> >   stable_api_nonsense.txt
> >   stable_kernel_rules.txt
> >   SubmitChecklist
> >   SubmittingDrivers
> >   SubmittingPatches
> >   volatile-considered-harmful.txt
>
> How about adding;
> kernel-doc-nano-HOWTO.txt

The problem is, the generated htmdocs are in english.  This file is about how 
to generate (and author) English documentation that won't be translated.  
What's the point of translating the instructions if the result won't be 
translated?

On the other hand, if the authors of patches _do_ put javadoc comments into 
the source code, the language maintainer should be aware of them and should 
have some easy way to translate them for the list...

> These three slightly include some policy in the documents but purpose
> are mostly technical. (So, it's just comment)
> devices.txt
> kernel-parameters.txt
> unicode.txt

Extracting the policy out into separate documents I could see, but I agree 
those are primarily technical.

Rob
-- 
"One of my most productive days was throwing away 1000 lines of code."
  - Ken Thompson.