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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

On 08/04/2015 05:35 PM, Mark Brown wrote:
> On Tue, Aug 04, 2015 at 03:50:33PM +0300, Laurent Pinchart wrote:
>> On Monday 03 August 2015 08:33:11 Jonathan Corbet wrote:
> 
>>> The nice thing about formats like Markdown or ReST is that they *are*
>>> plain text for all practical purposes.  Much better than DocBook in that
>>> regard.
> 
>> My problem with inline documentation is that it makes easier for developers to 
>> write crappy doc and believe they've done their duty. It's not a technical 
>> issue, and I believe inline documentation has merits, especially for API 
>> documentation, but I've seen too many kerneldoc comments written as
> 
> That's not really anything to do with the fact that the documentation is
> inline, it's more to do with documentation that people are forced to
> write without any obvious interest being shown in the results.  Anything
> else that's done as a pure checkbox effort will have similar effects.
> 
>> That's just useless. Worse, it can give the impression to reviewers that the 
>> function has been documented while it clearly hasn't. Maybe we just need to 
>> tighten the review process and push harder for documentation, at the risk of 
>> rejecting useful contributions. That's not a new problem though.
> 
> I'm not sure that more requirements for documentation will help that
> much, there's a definite skill in writing and review documentation which
> isn't all that common.  Insisting on people writing more without doing
> something to address that may just result in more bad documentation, but
> of course it's a really hard problem to address :(

While it's clear that, like skill at coding, skill at documentation
is wildly variable, almost everyone gets better at it with practice! Like
most problems, the problem would be more tractable if people were paid to
work on this. For a short while, there was an LF documentation fellowship
that had a goal to help things here. It had variable success. For a some
months it supported me (as the second holder of the fellowship) to work
full time on man pages, but there was so much man pages work, that kernel
docs didn't get too much of a look in. And then a few months later
(2008 crash), the funds went away. I raised the topic of reanimating
that fellowship a couple of times subsequently, but nothing came of it. 
That was however quite a few years ago. Given recent initiatives
from LF (such as the Critical Infrastructure Initiative), I wonder
whether it's worth someone checking in with LF about the possibility
of getting this going again. One thing I'd caution against though is
the idea that someone can just be paid to write kernel documentation.
Many parts of the kernel require significant time just to grok what's
going on, let alone document it. A much more efficient route to 
producing good documentation would I think be to have someone
with solid writing skills (as well as coding skills) support others
(i.e., subsystem developers and maintainers) to produce documentation,
by providing writing assistance, technical review, editing, and so on.
Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/