Re: [TECH TOPIC] Kernel documentation

[Thorsten Leemhuis <linux@leemhuis.info>]

On 16.06.23 19:48, Jonathan Corbet wrote:
> The documentation discussion at past kernel summits has been lively, so
> I think we should do it again.  Some topics I would bring to a session
> this year would include:
> 
> - The ongoing restructuring of the Documentation/ directory.  I've been
>   slowly moving the architecture docs into Documentation/arch/, but
>   would like to do more to reduce the clutter of the top-level directory
>   and make our documentation tree more closely resemble the organization
>   of the source.
> 
> - Structure.  We continue to collect documents, but do little to tie
>   them together into a coherent whole.  Do we want to change that and,
>   if so, how?

I wonder if it we should try to get some external input for these points
from people with (a) experience in the field and (b) an untainted
viewpoint. And no, I'm not talking about bringing in McKinsey or
PricewaterhouseCoopers. ;) I mean people that are not regularly
contributing to Linux, but have experience with writing docs for
(ideally large) Open Source projects and/or reorganizing large chunks of
docs that accumulated in a project over many years.

Does maybe anyone reading this have ties to someone from groups like
Write the Docs (https://www.writethedocs.org/)? Maybe someone there
might have the right experience and at the same time be willing to
provide us with some input or guidance.

Or do Linux distributors like Red Hat and SUSE maybe have an interest in
improving upstream kernel docs, because it might make their work easier?
If they have at least a little interest, they might be willing to ask
their docs teams to provide a few ideas for us. And if they care a lot,
it might even be quite relevant...
> - Support for documentation work.  There is nobody in the community who
>   is paid to put any significant time into documentation, and it shows.
>   How can we fix that?

...for this point. Or was this tried already without success?

Regarding contacting external people for input or help: I met someone on
two or three conferences that was involved in "Write the Docs", but that
was years ago and I don't know if that person is still active in that
space. I also know somebody that at least used to work on docs for Suse,
but afaik not in the kernel space.

I could ask those two if that's wanted.

But I wonder if somebody here has better connections that would be a
better angle of approach (especially to the docs teams for RH and SUSE).

Side note: during last years session there was someone with many good
ideas in the chat, which Willy read to the audience. It was a partner of
a kernel developer iirc. Maybe that person might also be a good fit to
ask for advice, too.

> [...]

Ciao, Thorsten