[Ksummit-discuss] [CORE TOPIC] Documentation

[Mark Brown]

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 :(

> If we don't start treating documentation as equally valuable as code we will 
> never fix the problem. I'd even argue that documentation should be treated as 
> having more value than code.

The documentation I tend to read is commit logs, those we do tend to
value much more and it shows.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: Digital signature
URL: <http://lists.linuxfoundation.org/pipermail/ksummit-discuss/attachments/20150804/674a31a3/attachment.sig>