[Ksummit-discuss] [CORE-TOPIC] Documentation
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Mon Jul 13 23:01:40 UTC 2015
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 at 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
More information about the Ksummit-discuss
mailing list