linux-kernel - Re: [PATCH v2 0/4] Rewrite the top-level index.rst

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <7f02143c-461f-268b-0f17-7fe20a7423d6@leemhuis.info>
Date:   Fri, 23 Sep 2022 10:55:08 +0200
From:   Thorsten Leemhuis <linux@...mhuis.info>
To:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc:     linux-kernel@...r.kernel.org, Kees Cook <keescook@...omium.org>,
        Jani Nikula <jani.nikula@...ux.intel.com>
Subject: Re: [PATCH v2 0/4] Rewrite the top-level index.rst

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