
The Problem with Linux Kernel Documentation, and How We're Fixing It - buovjaga
https://blogs.s-osg.org/problem-linux-kernel-documentation-fixing/
======
kashyapc
Related: Tomorrow [29-SEP-2016] afternoon at 15:00-15:40 CET, Jon Corbet of
LWN, is giving a talk[1] at Linux Recipes conference in Paris on this subject.

URL[2] to live streaming.

[1] [https://kernel-recipes.org/en/2016/talks/kernel-
documentatio...](https://kernel-recipes.org/en/2016/talks/kernel-
documentation-what-we-have-and-where-its-going-2/)

[2] [https://air.mozilla.org/kernel-recipes-2016-09-29-PM-
Session...](https://air.mozilla.org/kernel-recipes-2016-09-29-PM-Session/)

------
AstralStorm
The main problem is not the format of the documentation, but lack thereof.
Many important functions and high level implementation tasks are not
documented or the docs are inadequate.

~~~
proaralyst
Perhaps there's little documentation _because_ it has a poor format.

~~~
qplex
Not because of Programmers who think that the time spent writing documentation
would be better spent programming some more? ;)

~~~
wtetzner
No reason it couldn't be both, I suppose.

~~~
Jtsummers
Definitely the case in my office. A couple of opinionated and (relatively)
senior devs that think the code is the documentation. No, I can't read this 40
yo fortran code and use it as the basis for a new program on a different
architecture. It uses gotos and variables like "yxtgn" that mean nothing to
the reader (turned out y meant it was an integer, weird). I spent a month on
that because there was no documentation, which took up a page once I was done
writing it after my reverse engineering effort.

And then documentation, where it exists, is often poorly CM'd word documents,
and poorly OCR'd PDFs (or doc->pdf that somehow lost the ability to be
searchable and selectable text, what option did they select?!?).

The offending systems are only maintainable because a few people haven't
retired (< 1 year left for several of them) and sheer force of will for the
rest of us.

~~~
dozzie
> It uses gotos and variables like "yxtgn" that mean nothing to the reader
> (turned out y meant it was an integer, weird)

It meant "ynteger". Elementary, my dear Watson.

------
Sanddancer
They missed a format that's ubiquitous, has a lot of formatting options, and
has search facilities. Manpages. When someone's looking for a piece of
documentation, they are usually working on a system as they do it, and man -k
<thing> is a lot easier to remember than some other search tool that requires
its own set of packages, etc.

~~~
dend
The problem with that approach is that you are limiting yourself to
fundamentally primitive documentation (and by primitive I mean non-
interactive). Granted, for a kernel it might be less important, but it's great
when there is a good architecture diagram/image instead of 7 paragraphs.

~~~
Sanddancer
Manpages can have a rather large amount of interactivity. Documents can be
formatted as text, as HTML, with links, etc. The problem is that manpages are
an afterthought in too much of the Linux ecosystem, so people have low
expectations and low beliefs in what they can actually do. They can have
tables, they can have equations, they can have graphics.

~~~
dend
Out of genuine curiosity, could you link me to an existing guide from the
Linux community that is based on manpages and features images and/or other
interactive content?

~~~
jap
Not exhaustive, but I've written code that processes 50,000 or so man pages
and haven't hit one.

------
eliben
Happy to see they pick ReST over MD. ReST is vastly superior for these
purposes, in my experience.

~~~
Poiesis
Mind explaining why? I like Markdown but would like to know what ReST does
better.

~~~
has2k1
ReST can be better extended without creating a variant of the markup language
[1]. Extension support is first class [2], and it is by that means that a good
number of the core features are implemented.

[1] For example, github flavour, stackoverflow flavour, reddit flavour, ...

[2] Roles and directives.

------
sohkamyung
I find it surprising that Michael Kerrisk's Linux man-pages project isn't
mentioned here [1]. He and other contributors done a major job documenting the
Linux man pages. It's usually the first place I go to when I need to read up
on the Kernel APIs or C libraries.

\- [1] [https://www.kernel.org/doc/man-pages/](https://www.kernel.org/doc/man-
pages/)

------
jbergens
Are there any specification for ReST? With tests that confirm if a parser
works?

Otherwise it will be harder to get more tools.

------
X86BSD
They should contact the freebsd-doc@ folks.

