Message-ID: <87tu5ooaii.fsf@meer.lwn.net>
Date:   Sat, 03 Sep 2022 07:25:25 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Thorsten Leemhuis <linux@...mhuis.info>, linux-doc@...r.kernel.org
Cc:     linux-kernel@...r.kernel.org
Subject: Re: [PATCH 0/4] Rewrite the top-level index.rst

Thorsten Leemhuis <linux@...mhuis.info> writes:

> Great initiative. But looking at the rendered result made me wonder:
> what overall structure for the docs are you aiming for in the end? I'm
> sure you have a picture in your head, but I failed to grasp it, as for
> me a few things looked a little odd:

Thanks for taking a look!

> * we do all of this for the users, so shouldn't the section aimed at
> users be at the top? And list more things they will look for?

My thinking is that the main consumers of the kernel docs is kernel
developers (I can't prove this, I just know it :), and that I see a lot
of referrals to the process documentation.  So I started with that.  I'm
not wedded to that organization if something else seems better.

> * What is so important about "Architecture-agnostic documentation" and
> "Architecture-specific documentation" (both with just one entry) that
> they have to be listed here? Same for "Firmware-related documentation".

I kind of ran out of energy after moving a lot of stuff from the front
page and wasn't sure what to do with them.  There's definitely room for
improvement. 

> And is the User-oriented section really the right place for the kbuild
> stuff, as from a quite look it seems most of those aim at developers and
> not at users?

I guess I saw building and installation as a *use* of the kernel.  This
one does sort of cross the lines and could certainly go somewhere else.
I was mostly trying to avoid a bunch of subsections with a single entry. 

> * Quite a few things I'd had expected on that front page aren't listed
> there. Sure, everybody has different expectations on what's important,
> but I for example hat expected "command-line parameters" or "Reporting
> issues" (here I'm obviously biased) to be somewhere on that page.

I'm happy to change the mix; "reporting issues" probably does belong
there, at least.  As long as we don't get back to the current state
where *everything* is on the front page.

> This made me think: should that main index page maybe just have these
> three sections (apart from Translations) ?
>
> * User-oriented documentation
> * Application-developer documentation
> * Other documentation on the Linux kernel and its development

That relegates an awful lot of our important stuff to "other"; as said
above, I think that the main consumers of the documentation are kernel
developers, and the documentation organization should reflect that.

> I'd say that makes it quite clear where readers need to go from there,
> even if the name of the third section is a bit vague (but in contrast it
> becomes clear I'd say).
>
> Each section could list its five to ten most important documents before
> linking to a separate index file with more. And that index file for will
> need subcategories, too, otherwise it will become large, too.
>
> And sure, quite a few documents will be hard to categorize currently.
> Making things fit properly might take a decade or two (unless somebody
> hires a few people to bring order into this). But it would set a clear
> direction. It also would tell doc writers what tone and detail level to
> use when writing their texts, as that depends on the audience which
> becomes clearer this way.

The creation of a bit more structure is certainly one of the goals here.
After several years I'm not having to argue quite so much about grouping
documentation for the intended readers, so it seems like time to stir
things up again :)

> Ciao, Thorsten
>
> P.S.: /me wonders if Jonathan posted this patch-set as a bait and will
> force everyone replying to come to his LPC/kernel summit session "What
> kernel documentation could be"
> /me despite this replied, as he had planned to go anyway

An awful lot of kernel work gets done on conference-presentation
deadline schedules...  The session would be a good time to talk about
what we think our overall structure should be.

I will try to do another pass on this before then, but there's no
guarantees.  If nothing else, it'll clean up the bottom-of-page
messiness where I got lazy the first time.

Thanks,

jon

Powered by blists - more mailing lists