Re: [Ksummit-discuss] [CORE-TOPIC] Documentation

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

On Monday 13 July 2015 17:42:44 Jason Cooper wrote:
> On Mon, Jul 13, 2015 at 12:37:50PM -0400, Steven Rostedt wrote:
> > On Mon, 13 Jul 2015 12:47:23 +0300 Alexey Dobriyan wrote:
> > > Newbies should not write documentation because they, by definition,
> > > have little knowledge of the code. It will lead to many, many useless
> > > and redundant comments like below whose only purpose is stealing
> > 
> > > vertical whitespace:
> > I agree that newbies shouldn't write documentation.
> 
> I semi-disagree.  Assuming you meant newbies here as you defined below.
> 
> Not that an exception should make the rule, but please take a look at
> the Crypto API documentation (with userspace example code!) written by
> Stephan Mueller:
> 
>   git log --author="smueller@chronox.de"
> 
> His first patch was in May 2014.
> 
>   541af946fe13 crypto: drbg - SP800-90A Deterministic Random Bit Generator
> 
> By Nov/Dec 2014 he had documented the entire crypto API.
> 
>   52744af3af97 crypto: doc - document uncovered member variables
>   47ca5be9eb06 crypto: doc - HASH API documentation
>   16e61030aecb crypto: doc - CIPHER API documentation
>   58284f0d6c4a crypto: doc - BLKCIPHER API documentation
>   fced7b02623e crypto: doc - AEAD API documentation
>   f13ec330a787 crypto: doc - ABLKCIPHER API documentation
>   0d7f488f0305 crypto: doc - cipher data structures
>   968ab2910780 crypto: doc - SHASH API documentation
>   90240ffb1277 crypto: doc - AHASH API documentation
>   5d8c723f61f2 crypto: doc - hash data structures
>   aa1b6fbcbeac crypto: doc - RNG API documentation
>   e63b673f601d crypto: doc - userspace interface spec
>   e9a44230dbca crypto: doc - compile crypto API spec
>   7d12993ed890 crypto: doc - crypto API high level spec
> 
> Often the best person to write the docs for a newcomer to understand is
> someone who was just recently a newcomer.

I agree. Not that I want to show off, but there's at least another example.

9cad9c95d7e8 Documentation: DocBook DRM framework documentation

> > But maybe what they
> > can do is to question what a function does. And perhaps poke the
> > maintainer (or author of said function) to write something that
> > explains that function (only for non-static functions).
> 
> Submitting patches is often the *best* way to poke a maintainer. ;-)
> 
> I know I'm not the only one who would find it a lot easier to tweak an
> 80% correct documentation patch as opposed to explaining the function
> call, how it fits in with the others, how it historically evolved that
> way, etc.
> 
> > Now, I say "newbies" but I would really mean experienced developers
> > that are new to a subsystem. We don't need silly questions. Something
> > more on the line of one experienced kernel developer reading some code
> > of the kernel they have no idea about, and if they can't figure out
> > what a function does, ask the question to the author. Perhaps we can
> > get better documentation of internal interfaces out of it.

-- 
Regards,

Laurent Pinchart