linux-kernel - [PATCH 0/1 RESEND] docs: Include simplified link titles in main page's 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-next>] [day] [month] [year] [list]

Message-ID: <58e78693-82d1-451d-a546-51fb64ef6eb5@vt.edu>
Date:   Sun, 10 Dec 2023 19:19:12 -0600
From:   Carlos Bilbao <bilbao@...edu>
To:     Jonathan Corbet <corbet@....net>
Cc:     Miguel Ojeda <miguel.ojeda.sandonis@...il.com>,
        alex.gaynor@...il.com, wedsonaf@...il.com, boqun.feng@...il.com,
        gary@...yguo.net, bjorn3_gh@...tonmail.com, benno.lossin@...ton.me,
        a.hindborg@...sung.com, aliceryhl@...gle.com,
        "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        bilbao@...edu
Subject: [PATCH 0/1 RESEND] docs: Include simplified link titles in main
 page's index

NOTE: I'm resending because this patch set ended up labeled as Junk/Spam for
me and I suspect it will happen to others.

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.

I've uploaded screenshots of the website's main entry before and after [1]
and I personally find the simplified version cleaner and more user-friendly.

At some point, we could discuss an automated way to collect and display all
link titles, IMO manually doing it on the main page is a step in the
right direction for now.

Thanks,
Carlos

[1] https://github.com/Zildj1an/linux-kernel-docs-compare/blob/main/comparison.png

Carlos Bilbao (1):
    docs: Include simplified link titles in main page's index

Documentation/index.rst | 50 ++++++++++++++++++++---------------------
 1 file changed, 25 insertions(+), 25 deletions(-)