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

[Davidlohr Bueso <dave@stgolabs.net>]

On Sat, 2015-08-01 at 16:41 +0200, Jonathan Corbet wrote:
> There could, I think, be value in talking about where we would like our
> docs subsystem to go.  

Perhaps more important would be focusing on ways of _improving_ our
already existing Documentation/*. Some areas really stink, a combination
of stale and incorrect information. My brain is too melted to give exact
examples, just one of those things you run into.

In general core kernel docs is pretty well maintained. This, I believe,
is a result of maintainers pushing for quality docs with patches. I
don't know about others, ie drivers, but perhaps examples could be taken
from -tip, or akpm.

> What kind of changes would we like to make to render
> our docs more accessible, more current, and easier to contribute to?

I would say that if anyone has anything meaningful to say, he or she,
will find the way. As you mentioned, nicely formatted plain text files
work well.

While I don't discourage it, I am not a fan of automated documentation.
As you and mtk would know, writing high quality, informative, systems
software documentation is an involved process. And it should be, imo.
Same goes for describing APIs and algorithms in code comments. Sure,
automation has its pros, particularly keeping docs up to date; yet this
does not outweigh a well crafted document, which involves actual though.

Thanks,
Davidlohr