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 "Book" 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 - or just create our own theme.
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.
CHANGES from v1: I've tried to address the comments from v1, further
cleaning up the front page. I've added the "reporting issues" and "kernel
testing" documents there, and done a bit of cleanup. There is plenty more
yet to be done.
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.
Jonathan Corbet (7):
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
docs: move asm-annotations.rst into core-api
docs: Expand the front-page CPU-architecture section
docs: put atomic*.txt and memory-barriers.txt into the core-api book
Documentation/conf.py | 3 +-
.../{ => core-api}/asm-annotations.rst | 7 +-
Documentation/core-api/index.rst | 4 +
.../core-api/wrappers/atomic_bitops.rst | 18 ++
Documentation/core-api/wrappers/atomic_t.rst | 19 +++
.../core-api/wrappers/memory-barriers.rst | 18 ++
Documentation/index.rst | 154 ++++++------------
Documentation/process/index.rst | 1 +
Documentation/staging/index.rst | 42 -----
Documentation/subsystem-apis.rst | 58 +++++++
10 files changed, 172 insertions(+), 152 deletions(-)
rename Documentation/{ => core-api}/asm-annotations.rst (97%)
create mode 100644 Documentation/core-api/wrappers/atomic_bitops.rst
create mode 100644 Documentation/core-api/wrappers/atomic_t.rst
create mode 100644 Documentation/core-api/wrappers/memory-barriers.rst
create mode 100644 Documentation/subsystem-apis.rst
--
2.37.2
On Thu, 22 Sep 2022, Jonathan Corbet <[email protected]> wrote:
> 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.
I'm screaming for you to merge it already! It's a great stride forward.
FWIW,
Acked-by: Jani Nikula <[email protected]>
--
Jani Nikula, Intel Open Source Graphics Center
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
Thorsten Leemhuis <[email protected]> writes:
> 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
> ```
So every page remains accessible, just like they are now. They just
aren't linked directly from the front page - as many pages already are
not. I honestly don't understand what the problem is here.
*No* site links everything directly on its front page. Even if it had
an effect on search engines, I think it would be wrong to prioritize SEO
over basic usability.
>> 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.
Again ... who are the users? I maintain that the actual users of our
docs are primarily kernel developers.
>> 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.
I want to do it because it's a clear step forward and has already been
pending for a month. It is surely not perfect, and there will
undoubtedly be changes, perhaps big ones, to come, but I cannot imagine
a scenario where we want to go back to the mess we have now.
Thanks,
jon
On 23.09.22 15:45, Jonathan Corbet wrote:
> Thorsten Leemhuis <[email protected]> writes:
>
>> 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
>> ```
>
> So every page remains accessible, just like they are now. They just
> aren't linked directly from the front page - as many pages already are
> not. I honestly don't understand what the problem is here.
I'm not sure myself if there is a problem, I just wanted to bring that
LPC chat up, as it seemed Zsuzsa had a lot of experience with this sort
of problems at was at least somewhat interested in Linux kernel docs --
so I thought it might be worth bringing Zsuzsa into this discussion (but
I couldn't quickly find a email address to simply CC).
> *No* site links everything directly on its front page. Even if it had
> an effect on search engines, I think it would be wrong to prioritize SEO
> over basic usability.
Yeah, agreed. Something about SEO not being a priority was mentioned in
the chat, too.
>>> 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.
>
> Again ... who are the users?
I meant people just using the kernel, not developing the kernel itself
or developing software that's running on top of it.
> I maintain that the actual users of our
> docs are primarily kernel developers.
I guess you are right with that, but maybe that's just like that due to
the docs we have and not the docs we should have (or should aim for
having in the long run).
IOW: why is the kernel different from say LibreOffice, Firefox, or some
random command line app: if I look into the documentation (say because
I'm using that software for the very first time or because I have a
problem with it after using it for years) I don't expect to see lots of
docs at the most prominent place that are only relevant for people that
want to modify said software; I'd expect things like "what is this
software and how can I use it", "how can I install this software", "how
can I report a bug", and "what knobs are available to deal with corner
cases" there.
>>> 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.
>
> I want to do it because it's a clear step forward and has already been
> pending for a month. It is surely not perfect, and there will
> undoubtedly be changes, perhaps big ones, to come, but I cannot imagine
> a scenario where we want to go back to the mess we have now.
I understand and yes, maybe it's the right thing to do; but OTOH that
page is a mess for quite a while already, so is it really a big problem
to just leave it like that for 9 or 10 more weeks while trying to bring
in a few more people that might be able to directly bring us on a good
long-term course?
Ciao, Thorsten
Thorsten Leemhuis <[email protected]> writes:
>> I maintain that the actual users of our
>> docs are primarily kernel developers.
>
> I guess you are right with that, but maybe that's just like that due to
> the docs we have and not the docs we should have (or should aim for
> having in the long run).
>
> IOW: why is the kernel different from say LibreOffice, Firefox, or some
> random command line app: if I look into the documentation (say because
> I'm using that software for the very first time or because I have a
> problem with it after using it for years) I don't expect to see lots of
> docs at the most prominent place that are only relevant for people that
> want to modify said software; I'd expect things like "what is this
> software and how can I use it", "how can I install this software", "how
> can I report a bug", and "what knobs are available to deal with corner
> cases" there.
For better or for worse, our most prominent user-facing documentation is
the man pages, which are not a part of the kernel repository. (Hmm...it
wouldn't hurt to add a link to them to the front page, if and when a
site with current man pages exists again).
I don't have that much invested in the current ordering, we can
certainly change it - anytime we want. Anybody else have an opinion on
that topic?
>> I want to do it because it's a clear step forward and has already been
>> pending for a month. It is surely not perfect, and there will
>> undoubtedly be changes, perhaps big ones, to come, but I cannot imagine
>> a scenario where we want to go back to the mess we have now.
>
> I understand and yes, maybe it's the right thing to do; but OTOH that
> page is a mess for quite a while already, so is it really a big problem
> to just leave it like that for 9 or 10 more weeks while trying to bring
> in a few more people that might be able to directly bring us on a good
> long-term course?
I guess my feelings are that (1) I've had enough promises to help with
documentation over the years to learn not to count on such until said
help actually materializes, and (2) demonstrating what we can do can, I
hope, only inspire people who know more than me to show what we *really*
can do...
Thanks,
jon
On Fri, Sep 23, 2022 at 09:03:36AM -0600, Jonathan Corbet wrote:
> For better or for worse, our most prominent user-facing documentation is
> the man pages, which are not a part of the kernel repository. (Hmm...it
> wouldn't hurt to add a link to them to the front page, if and when a
> site with current man pages exists again).
Oh, yes, good idea!
> I don't have that much invested in the current ordering, we can
> certainly change it - anytime we want. Anybody else have an opinion on
> that topic?
I think you, as the recognized leader of the doc project, can
establish some guiding principles on this, providing a bit of top-down
order. e.g. adopt a specific "Linux kernel documentation project mission
statement / strategy" that takes a distinctly opinionated stand on
anything that has been debated. For example, a strawman, not meant
to block this series in any way:
Our primary audience is kernel developers, especially new
contributors. Our next priority is people who want to engage
with the developer community, but may not strictly be kernel
developers (e.g. testers, bug reporters, researchers, press,
etc). Next is users of the kernel, especially for how to use
various features or configurations.
Topics are ordered from least complexity to greatest complexity,
with ties solved alphabetically.
Links to development conversations must use Lore URLs unless
they are specifically not available.
Links to external documentation is strongly encouraged. Any
dead links will be removed if not updated within 6 months.
The "htmldocs" build target is expected to build without
warnings.
It could live in Documentation/doc-guide/contributing.rst, and be the
tie-break for anything that comes up. Obviously, it, too, could change.
> I guess my feelings are that (1) I've had enough promises to help with
> documentation over the years to learn not to count on such until said
> help actually materializes, and (2) demonstrating what we can do can, I
> hope, only inspire people who know more than me to show what we *really*
> can do...
Ship it! "Patches welcome", etc. :)
--
Kees Cook
On 9/23/22 06:45, Jonathan Corbet wrote:
> Thorsten Leemhuis <[email protected]> writes:
>
>> 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.
>>
>
> Again ... who are the users? I maintain that the actual users of our
> docs are primarily kernel developers.
ACK!
--
~Randy
On Fri, Sep 23, 2022 at 09:03:36AM -0600, Jonathan Corbet wrote:
> >> I want to do it because it's a clear step forward and has already been
> >> pending for a month. It is surely not perfect, and there will
> >> undoubtedly be changes, perhaps big ones, to come, but I cannot imagine
> >> a scenario where we want to go back to the mess we have now.
> >
> > I understand and yes, maybe it's the right thing to do; but OTOH that
> > page is a mess for quite a while already, so is it really a big problem
> > to just leave it like that for 9 or 10 more weeks while trying to bring
> > in a few more people that might be able to directly bring us on a good
> > long-term course?
>
> I guess my feelings are that (1) I've had enough promises to help with
> documentation over the years to learn not to count on such until said
> help actually materializes, and (2) demonstrating what we can do can, I
> hope, only inspire people who know more than me to show what we *really*
> can do...
Just to throw my hat in the ring here for the discussion -- I think we
need to bear 2 things in mind:
1. Reorganizing the front page for docs is probably something that's
disproportionately susceptible to bikeshedding. I don't think that's
happening in this specific discussion, but rather, I think we have to be
cognizant to not let ourselves drown in getting 100% consensus on
something like this given that it's likely to garner a lot of subjective
opinions. I am not trying to straw-man Thorsten's point here because I
don't think he's claiming this isn't true, but rather just point out
that it might be better to land something now that's strictly an
improvement, and then worry about perfecting it later, precisely because
otherwise we'll probably just spend forever livelocking on it.
2. I think we can all agree that what we have now, i.e. listing every
single link on the front page, is really bad. Having hundreds of links
on the front page is actively worse than having just a few, because none
of them have any meaning anymore. Given that the index is easy to see
and click on if anyone wants to go back to "show me all the links" mode,
my perspective is that we should just land this as is, and worry about
perfecting the layout / specifics later.
Thanks,
David