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

Mike Rapoport
2020-06-18T09:09:02Z

On Tue, Jun 09, 2020 at 02:53:53PM -0600, Jonathan Corbet wrote:
> The long process of converting the kernel's documentation into RST is
> finally coming to an end...what has that bought us? We have gone from a
> chaotic pile of incomplete, crufty, and un-integrated docs to a slightly
> better organized pile of incomplete, crufty, slightly better integrated
> docs. Plus we have the infrastructure to make something better from here.
>
> 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? What sorts of improvements to the build
> infrastructure would be useful? I'll come with some ideas (some of which
> you've certainly heard before) but will be more interested in listening.

Antoher question I've been asking myself is what to do with good but old
guides. For instance, Documentation/virt/uml/user_mode_linux.rst
describes how to debug the kernel with gdb, but most of the code
references there are stale by now.

Another example is "Unreliable Guide To Hacking The Linux Kernel"
(Documentation/kernel-hacking/hacking.rst). It's really nicely written
by it is way too out of date.

> jon

--
Sincerely yours,
Mike.