[Ksummit-discuss] [CORE TOPIC] Documentation

[Rafael J. Wysocki]

On Sunday, August 02, 2015 12:07:14 AM Davidlohr Bueso wrote:
> 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.

"thought" I guess?

I have to say I agree here.

Not to mention the fact that if you are browsing the kernel tree via a web
frontend or LXR, for example, plain text docs are really good to have.

Thanks,
Rafael