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

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

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).

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 may actually be
easier for a newcomer than an experienced developer to do so: they would
already be in the right shoes to notice bad documentation flow. We would
however need a newcomer with a combined interest in a particular topic
and in its documentation, and with time to refactor the latter.

-- 
Regards,

Laurent Pinchart