[Ksummit-discuss] [CORE TOPIC] Documentation
Jonathan Corbet
corbet at lwn.net
Mon Aug 3 14:33:11 UTC 2015
On Mon, 03 Aug 2015 15:35:36 +0200
"Rafael J. Wysocki" <rjw at rjwysocki.net> wrote:
> > 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.
Surely nobody thinks I was saying that the documentation-writing process
can be automated! :) But we go to some lengths now to document our APIs
in the code; I don't think we would want to break that.
> 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.
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.
jon
More information about the Ksummit-discuss
mailing list