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

[Michael Ellerman <mpe@ellerman.id.au>]

On Sat, 2015-08-01 at 16:41 +0200, Jonathan Corbet wrote:
> As your relatively new documentation subsystem maintainer, I think there
> might be reason to talk about docs for a bit at the summit.
> 
> Currently, we have two major branches to our docs.  One, the bulk of
> Documentation/, is a haphazard collection of text files of varying quality
> and applicability to current kernels.  The other is a set of more
> organized DocBook documents.
> 
> Despite their disorganized nature, the plain-text docs get the bulk of the
> attention.  Anybody can manage to work with a text file.  The DocBook
> stuff, instead, is kind of a pain.  Working in DocBook itself is less
> than fun, few people dare to delve into the code that builds the docs,
> and the whole thing is rather fragile.  Changing a struct to a union in
> the wireless subsystem a few months back broke the docs build, for
> example; few people test for such things and even fewer seem to know how
> to fix them.
...
> 
> I am not convinced that DocBook is really the right tool for the job
> here.  It is complex, finicky, and it's a real pain to have to replace an
> entire laptop because you've worn out your shift key.  It is, I believe, an
> impediment to improvements to our docs in general.  If, instead, we used
> something more plain-text-like, I think life might get a lot easier; it
> could also enable the integration of all of our docs into something a bit
> more cohesive.

Yeah +1 from me on getting rid of DocBook.

I looked at it a bit in terms of asking people to write docs, and decided it
was too painful to impose on people.

I know it's not *that* hard, but it's harder than it needs to be for the value
it brings IMHO.

> Markdown in one of its many forms might be a good alternative here.  I'm
> also somewhat attracted by Sphinx, which is designed for documenting code
> already and could probably be made to work well with our existing kerneldoc
> comments without a whole lot of trouble.  The Sphinx idea, though, is
> hobbled by the inconvenient fact that I've not had the time to develop it
> far enough to even have a vague idea of whether it would make real-world
> sense.

I'd vote for Markdown. It's very unobtrusive, reads nicely as plain text, and
all the young kids know it from writing Github README.md files.

cheers