Date: Mon, 18 Dec 2023 09:57:08 -0600
From: Carlos Bilbao <carlos.bilbao@....com>
To: Jonathan Corbet <corbet@....net>, Carlos Bilbao <bilbao@...edu>,
 Miguel Ojeda <ojeda@...nel.org>
Cc: Alex Gaynor <alex.gaynor@...il.com>,
 Wedson Almeida Filho <wedsonaf@...il.com>, Boqun Feng
 <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>,
 Björn Roy Baron <bjorn3_gh@...tonmail.com>,
 Benno Lossin <benno.lossin@...ton.me>,
 Andreas Hindborg <a.hindborg@...sung.com>, Alice Ryhl
 <aliceryhl@...gle.com>, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org, rust-for-linux@...r.kernel.org
Subject: Re: [PATCH 0/1] docs: Include simplified link titles in main page's
 index

On 12/15/23 09:47, Jonathan Corbet wrote:
> Carlos Bilbao <bilbao@...edu> writes:
> 
>> The general consensus is that the documentation's website main entry point
>> and its sidebar leave room for improvement.
>>
>> Something we can easily fix is that there's too much duplicated text.
>>
>> To that point, consider the titles "The Linux kernel user's and
>> administrator's guide" and "The Linux kernel user-space API guide." We get
>> it, it's the Linux kernel. It's assumed that everything listed pertains to
>> the Linux kernel, given the overarching title, "The Linux Kernel
>> documentation." Constant repetition of "Linux" and "kernel" (45 times
>> each), "documentation" (21 times), and "guide" (18 times) are excessive and
>> affect UX.
>>
>> I propose simplifying without altering actual document titles, the text
>> linking to these documents on the main page ("link titles"). For example,
>> "The Linux kernel user's and administrator's guide" could become "User's
>> and Administrator's Guide," and "A guide to the Kernel Development Process"
>> could be "Development Process". This is what my patch does.
> 
> So I totally agree that the sidebar can use improvement, and I agree
> that this patch makes it better.
> 
> I'm less convinced about the changes to the page itself, which I
> consider to be somewhat more important.  There, I think, the more terse
> titles are likely to be less useful for readers.  (OTOH, I think the
> result is an improvement for those reading the RST files).
> 
> I spent some time a little while back understanding how the sidebar is
> generated, and feel that we can make it into what we want it to be.  But
> I don't think we've decided what we really want it to be.  I think there
> is simply too much stuff there in general; it's never going to be
> manageable that way.
> 
> There was a suggestion at the kernel-summit session to just put the
> top-level books there:
> 
> 	Kernel documentation
>          Development-process guide
>          Core API manual
>          Driver API manual
>          User-space API manual
>          Maintainer guide
>          Documentation guide
> 
> Then perhaps add one level for whichever book is open (if any) at the
> time.

I like this idea; as of today, we have too many duplicated links.

Regarding the addition of concise titles for the link titles, I'd argue
that the important part is not to lose information. For example, I
shortened "Submitting patches: the essential guide to getting your code
into the kernel" to "Submitting patches". But, if I had simply put
"Patches", it would have made it unclear what the document was actually
about.

> 
> I'm sure there are other, better ideas as well.
> 
> Meanwhile, I'm pondering on this patch, would like to know what others
> think.  Carlos nicely put up some comparison images for us:
> 
>    https://github.com/Zildj1an/linux-kernel-docs-compare/blob/main/comparison.png
> 
> ...so it's not necessary to build the docs to see the results.
> 
> Thanks,
> 
> jon
> 

Thanks,
Carlos

Powered by blists - more mailing lists