Re: [PATCH 0/1] docs: Include simplified link titles in main page's index

[Carlos Bilbao]

On 12/15/23 09:47, Jonathan Corbet wrote:
> Carlos Bilbao <bilbao@xxxxxx> 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