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] [thread-next>] [day] [month] [year] [list]
Date: Wed, 21 Feb 2024 13:40:00 -0700
From: Jonathan Corbet <corbet@....net>
To: Carlos Bilbao <carlos.bilbao@....com>, 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

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.

Thanks,

jon

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ