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

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] [day] [month] [year] [list]

Date: Thu, 22 Feb 2024 08:34:12 -0600
From: Carlos Bilbao <carlos.bilbao@....com>
To: Jonathan Corbet <corbet@....net>, rdunlap@...radead.org,
 vegard.nossum@...cle.com
Cc: bilbao@...edu, linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 0/2] docs: Include simplified link titles in main index

On 2/21/24 14:40, Jonathan Corbet wrote:
> Carlos Bilbao <carlos.bilbao@....com> 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