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

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

On Monday 13 July 2015 21:20:32 Peter Hüwe wrote:
> Am Montag, 13. Juli 2015, 11:47:23 schrieb Alexey Dobriyan:
> > On Mon, Jul 13, 2015 at 1:38 AM, Peter Hüwe <PeterHuewe@gmx.de> wrote:
> > > as we talked about recruiting in the other thread I realized that one
> > > thing that might reduce the entrance barrier a bit (apart from tooling
> > > and flow) would be proper documentation.
> > 
> > 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:
> While I agree with your 'stupid documentation is stupid' argument, I tend to
> somewhat disagree about that newbies should not write documentation.
> 
> By newbies I do not mean someone new to programming - that of course makes
> no sense - but why shouldn't a experienced c-programmer who is currently
> figuring out how the kernel works not document stuff along the way?

I fully agree, as I've gone through that process when I wrote my first DRM/KMS 
driver, and found it very valuable.

Writing documentation is a very good way to try and understand a subsystem for 
newcomers. It's time consuming though, which goes in the way of the tight 
schedules everybody seems to have. Furthermore employers are unfortunately not 
usually keen to fund documentation, especially when the schedule is tight.

On the other hand, I realized that writing down my findings while I was 
exploring the DRM subsystem was a great way to learn about it. It then took a 
bit of time to format my notes into proper documentation, but less than 
writing everything from scratch in one go. Taking notes also help structuring 
the documentation in a more natural way.

The picture wasn't all bright though. The documentation patch I submitted was 
of course not 100% complete, but the problem came later when the subsystem got 
rearchitectured without updating the documentation. Code changes were merged 
with kerneldoc comments to document functions, but the global DocBook 
architecture documentation was left untouched (except for integration of 
kerneldoc as API reference). The end result is that the DRM/KMS subsystem went 
from having a reasonable architecture documentation to being undocumented. 
Needless to say my motivation as a documentation writer for DRM/KMS took a big 
blow.

This being said, not everything is dark either. The V4L2 subsystem, for 
instance, does a pretty good job at keeping its documentation up-to-date. The 
maintainers and core developers always nack code changes that do not come with 
related documentation updates. This proved to be effective, but requires the 
rule to be strictly enforced. I wonder if this could scale to other 
subsystems, and what kind of other incentives we could create.

> I think that's much better than fixing whitespaces and long lines.

-- 
Regards,

Laurent Pinchart