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

[Jonathan Corbet <corbet@lwn.net>]

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