Re: [TECH TOPIC] Kernel documentation - update and future directions

[Jonathan Corbet <corbet@lwn.net>]

Laurent Pinchart <laurent.pinchart@ideasonboard.com> writes:

> Hi Jon,
>
> On Fri, Aug 22, 2025 at 04:55:51PM -0600, Jonathan Corbet wrote:
>> The last year has seen a massive amount of work in our documentation
>> build infrastructure and continuous improvement in the docs themselves.
>> This session will provide a brief update of what has happened recently,
>> followed by discussion on what we want to do next.  How would we like
>> our documentation to evolve in the next year or three?
>
> One area that I think could be improved is making documentation more
> accessible, in particular to newcomers. We have a really impressive (and
> ever increasing) amount of documentation that has mostly grown in an
> organic fashion. As a consequence, many answers can be found when one
> knows what they're searching for, but reading documentation is painful
> for newcomers. It doesn't flow naturally, and lots of concepts are used
> before being introduced much later (or in entirely different locations).

Trust me, I get it.  That's why I have pushed so hard to try to organize
the docs with the intended reader in mind.  I think that has worked out
well but, so far, the main effect has been to take a massive unorganized
pile of stuff and arrange it into several pile of stuff, hopefully with
slightly better organization.

Occasionally I make an attempt to attack one of the top-level books and
create a bit more order there.  But my teaspoon is going to take a while
to drain that ocean.

> While some documents are clearly meant to be reference material, other
> target developers who are not familiar with the topic being described.
> They would benefit from being written in linear, story-telling way. I
> don't know how to best achieve that though: developers writing any kind
> of documentation in the first place is already an achievement, and
> writing the documentation while putting yourself in the shoes of someone
> not familiar with the topic is not an easy task.

It is common to divide technical documentation into four broad
categories: tutorials (for learning), howtos (getting tasks done),
explanation (understanding what's going on), and reference.  Each is
aimed at a different audience.

Most of what we have is reference.  There's an occasional howto, and
some explanation in spots.  We don't have much in the way of tutorials.

It would be nice to (1) recognize those categories in the organization
of our documentation, and (2) fill them out somewhat.  But, as you note,
getting people to do that is hard.  Doing it properly requires somebody
whose job is to create that sort of material...and, as I've harped on
for years:

	Despite the fact that there are large number of people paid to
	work on the kernel, there is not a single person whose job is to
	work on kernel documentation.

Last year we tried an experiment with a bit of funding from the LF to
create a bit of paid documentation; for a number of reasons, that
experiment did not work out.  But it seems there should be a way to make
some forward progress on this front.

Thanks,

jon