mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
* [PATCH 0/1 RESEND] docs: Include simplified link titles in main page's index
@ 2023-12-11  1:19 Carlos Bilbao
  2023-12-11  1:20 ` [PATCH 1/1 " Carlos Bilbao
  0 siblings, 1 reply; 4+ messages in thread
From: Carlos Bilbao @ 2023-12-11  1:19 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Miguel Ojeda, alex.gaynor, wedsonaf, boqun.feng, gary, bjorn3_gh,
	benno.lossin, a.hindborg, aliceryhl, linux-doc,
	Linux Kernel Mailing List, bilbao

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(-)


^ permalink raw reply	[flat|nested] 4+ messages in thread
end of thread, other threads:[~2023-12-11  1:58 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-12-11  1:19 [PATCH 0/1 RESEND] docs: Include simplified link titles in main page's index Carlos Bilbao
2023-12-11  1:20 ` [PATCH 1/1 " Carlos Bilbao
2023-12-11  1:41   ` Randy Dunlap
2023-12-11  1:58     ` Carlos Bilbao

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®