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

On Tue, Jun 9, 2020 at 10:54 PM Jonathan Corbet <[email protected]> wrote:

> What are the next steps for kernel documentation?  What would we really
> like our docs to look like, and how might we find the resources to get
> them to that point?

We have a whole slew of quite basic introductory materials to the very
fundamental kernel data structures that are scattered all over the planet
and in the LWN kernel archive. All in often slightly dated variants.
Examples:
https://www.kernel.org/doc/gorman/html/understand/understand006.html
http://vger.kernel.org/~davem/skb_data.html

I suppose technical writers could benefit from a global TODO list with
this kind of subjects such as "document the basic arch interface",
"document what an skb is", "document how the page directory works".

Right now it is a mixture of read the code, "everybody knows how that
works" and random sources on the Internet, which isn't very helpful
to newcomers.

I second Vetters point to tie this documentation in tightly with the code
implementing it even pretty substantial text chunks IMO, the idea can be
attributed to Donald Knuth's book on literate programming from 1984,
and while he was a bit enthusiastic the idea isn't bad at all.

Yours,
Linus Walleij
_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss