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

Date: Wed, 21 Feb 2024 13:58:35 -0600
From: Carlos Bilbao <carlos.bilbao@....com>
To: 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

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.

> 
> ---
> 
> v1 Link: https://lore.kernel.org/lkml/58e78693-82d1-451d-a546-51fb64ef6eb5@vt.edu/T/
> 
> Changes since v1:
> 
> - Apply feedback:
>    Driver implementation API -> Driver APIs
>    Testing -> Testing guide
>    Hacking -> Hacking guides
>    User-space tools -> Userspace tools
>    User-space API -> Userspace APIs
>    CPU Architectures -> CPU architectures
> 
> - Include patch fixing the title of The Linux kernel user's and
>    administrator's guide.
> 
> - Minor changes: Change "main page's index" for "main index" in commit
>    subject. Also use my work email to sign the commits.
> 
> ---
> Documentation/admin-guide/index.rst |  1 +
> Documentation/index.rst             | 52 ++++++++++++++---------------
> 2 files changed, 27 insertions(+), 26 deletions(-)
> 

Thanks,
Carlos