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: <7f02143c-461f-268b-0f17-7fe20a7423d6@leemhuis.info>
Date:   Fri, 23 Sep 2022 10:55:08 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.2.1
Content-Language: en-US, de-DE
To:     Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org
Cc:     linux-kernel@vger.kernel.org, Kees Cook <keescook@chromium.org>,
        Jani Nikula <jani.nikula@linux.intel.com>
References: <20220922204138.153146-1-corbet@lwn.net>
From:   Thorsten Leemhuis <linux@leemhuis.info>
Subject: Re: [PATCH v2 0/4] Rewrite the top-level index.rst
In-Reply-To: <20220922204138.153146-1-corbet@lwn.net>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk


On 22.09.22 22:41, 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.

That's true, but is it maybe good or even important for googleability?
When you talked about this in your LPC talk this went on in the matrix chat:

```
Nur Hussein
I feel like every existing page needs to be accessible (somehow)
from that starting page

Zsuzsa Nagy

access to all pages <- findability from a search engine (technical
author talking here)

step #2 in-site search for those who already landed on your pages
```

It looks to me like Zsuzsa shared a lot of valuable comments on the chat
during the talk. I wonder if we should bring Zsuzsa into this discussion
before heading in a wrong direction, as that might result in some back
and forth that just confuses people reading the docs.

Maybe we should try to get even more people into the discussion that
write docs for a living. I guess there might be some people at Red Hat,
SUSE, or open source projects that have actual experience in bringing
structure into a big chunk of texts of a large open source project. Not
sure if we can get them to help us, but I guess it's worth a try.

> 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/

I still think we're doing all this to build something for users and
hence docs for users should be at the top spot. I'd even think "those
people are selfish" if I'd look into the docs of a software and find
texts for developers at the top spot.

> Unless I get screams I plan to slip this into 6.1.  It is definitely not
> the final form of the front page, but I doubt we'll ever get there; we can
> change it in whatever ways make sense.

My 2 cent: why the rush? I'd say: let's try to get some feedback from
Zsuzsa and experts on docs first. I'd be willing to approach them. If
that doesn't work out over the next few weeks, just merge what you have
for 6.2.

Ciao, Thorsten