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/

Those pages are rendered with the "Alabaster" theme, which pays attention
to the html_sidebar directive.  I am not proposing a switch to that theme
(I just picked it at random), but I do think we should reconsider the
default theme at some point.

This is only a beginning; I think this kind of organizational effort has to
be pushed down into the lower layers of the docs tree itself.  But one has
to start somewhere.


Jonathan Corbet (4):
  docs: promote the title of process/index.html
  docs: Rewrite the front page
  docs: reconfigure the HTML left column
  docs: remove some index.rst cruft

 Documentation/conf.py            |   3 +-
 Documentation/index.rst          | 157 +++++++++++--------------------
 Documentation/process/index.rst  |   1 +
 Documentation/subsystem-apis.rst |  56 +++++++++++
 4 files changed, 116 insertions(+), 101 deletions(-)
 create mode 100644 Documentation/subsystem-apis.rst

-- 
2.37.2

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

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

Thorsten Leemhuis <linux@leemhuis.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