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: <875yhep5l1.fsf@meer.lwn.net>
Date:   Fri, 23 Sep 2022 07:45:30 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Thorsten Leemhuis <linux@...mhuis.info>, 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

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