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