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

[Kees Cook <keescook@chromium.org>]

On Sat, Sep 03, 2022 at 12:03:17PM +0200, Thorsten Leemhuis wrote:
> 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/
> > [...]

I like it -- FWIW, I am able to find stuff much more easily with
this. I am traditionally looking most for internal API details, how
to test exposed userspace interfaces, and process docs (so I can send
reference links to contributors when I'm doing reviews). These map to
"how do I do it?", "how do I test it?", and "where can I aim people for
common process details?"

(So I'd expect to see
https://static.lwn.net/kerneldoc/dev-tools/testing-overview.html
linked under "Development tools and processes")

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

I'd agree with Jon: I expect the primary consumer to be new and existing
contributors. (Where "new" may just mean "new to this area of the code"
too.)

Under "Other documentation" on the front page that can move:
"Atomic Types", "Atomic bitops" can be moved to Core API docs under
"Data structures". I think "Memory Barriers" can go to "Concurrency
primitives".

-Kees

-- 
Kees Cook