Re: [TECH TOPIC] Kernel documentation

[Jan Kara <jack@suse.cz>]

On Wed 21-06-23 13:04:56, Thorsten Leemhuis wrote:
> 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...

I've forwared this email to our documentation team at SUSE if it sparks
some interest :)

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

Well, my feeling is that our doc team is rather overloaded with internal
work (documenting various products, doing translations to various languages
and what not) so they don't have many cycles for upstream work. Also for
the really technical stuff (like kernel APIs), it is often us, the
developers, that initially write say the tuning docs and the doc team then
takes it as a source of information and cleans it up to customer consumable
state ;) So the doc team is not even a direct consumer of the kernel docs
but us developers that try to prepare something for the doc team. Just my
2c about how it works at SUSE...

								Honza

-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR