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

[Dmitry Torokhov <dmitry.torokhov@gmail.com>]

On Mon, Aug 03, 2015 at 08:33:11AM -0600, Jonathan Corbet wrote:
> On Mon, 03 Aug 2015 15:35:36 +0200
> "Rafael J. Wysocki" <rjw@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.

My main issue with the DocBook is that it is not generated by default
and it is actually takes a while to generate them; otherwise I woudl
love to be able to catch at least issues breaking existing docs as early
as possible.

Thanks.

-- 
Dmitry