Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <938a9905-217c-f02a-b5c2-35c1e5d7822b@leemhuis.info>
Date:   Sat, 3 Sep 2022 12:03:17 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.2.0
Subject: Re: [PATCH 0/4] Rewrite the top-level index.rst
Content-Language: en-US, de-DE
To:     Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org
Cc:     linux-kernel@vger.kernel.org
References: <20220901231632.518583-1-corbet@lwn.net>
From:   Thorsten Leemhuis <linux@leemhuis.info>
In-Reply-To: <20220901231632.518583-1-corbet@lwn.net>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 02.09.22 01:16, Jonathan Corbet wrote:
> The top-level index.rst file is the entry point for the kernel's
> documentation, especially for readers of the HTML output.  It is currently
> a mess containing everything we thought to throw in there.  Firefox says it
> would require 26 pages of paper to print it.  That is not a user-friendly
> introduction.
<
> This series aims to improve our documentation entry point with a focus on
> rewriting index.rst.  The result is, IMO, simpler and more approachable.
> For anybody who wants to see the rendered results without building the
> docs, have a look at:
> 
>   https://static.lwn.net/kerneldoc/
> [...]

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:

* 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?

* 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".
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?

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

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

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.

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