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

[Jason Cooper <jason@lakedaemon.net>]

On Mon, Jul 13, 2015 at 12:37:50PM -0400, Steven Rostedt wrote:
> On Mon, 13 Jul 2015 12:47:23 +0300
> Alexey Dobriyan <adobriyan@gmail.com> 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.

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

thx,

Jason.