Re: [PATCH v2 0/2] docs: Include simplified link titles in main index

[Carlos Bilbao]

On 2/21/24 14:40, Jonathan Corbet wrote:
> Carlos Bilbao <carlos.bilbao@xxxxxxx> writes:
>
> > Hello,
> >
> > On 1/9/24 09:56, Carlos Bilbao wrote:
> > > 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.
> > >
> > > Also, I send a patch fixing the formatting of the title of
> > > admin-guide/index.rst (The Linux kernel user's and administrator's guide);
> > > a detail I noticed because the link title would not work otherwise.
> > >
> > > Thanks,
> > > Carlos
> > >
> > > Carlos Bilbao (2):
> > >       docs: Correct formatting of title in admin-guide/index.rst
> > >       docs: Include simplified link titles in main index
> >
> > Is there a reason why this patch set is currently on hold? It must to be
> > feeling a bit lonely by now.
>
> It's been sitting there because, as I explained in response to the first
> version, I'm not really convinced that it's the best idea.  We're
> trading off the readability of the main page to make things better for
> the sidebar, and I think there are better ways to improve the sidebar.
>
> That said, I've not managed to get around to experimenting with any of
> those better ways, and I don't see that happening anytime this side of
> the next merge window.
>
> So I'll go ahead and apply the series, but I do still intend to revisit
> this area when I can.

From my perspective, this improves readability for both the sidebar and
the main page, but I know that is a subjective perception. I look forward
to helping with alternative ways in the future.

> Thanks,
>
> jon

Thanks,
Carlos