[PATCH v2 0/2] docs: Include simplified link titles in main index

[PATCH v2 0/2] docs: Include simplified link titles in main index

[Carlos Bilbao]

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

---

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

[PATCH v2 1/2] docs: Correct formatting of title in admin-guide/index.rst

[Carlos Bilbao]

Adjust the title of "The Linux kernel user's and administrator's guide" to
adhere to the expected reStructuredText (rst) formatting, using double
equal signs for the main header.

Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
---
 Documentation/admin-guide/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 43ea35613dfc..af0fa0ff5d65 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -1,3 +1,4 @@
+=================================================
 The Linux kernel user's and administrator's guide
 =================================================
 
-- 
2.34.1

[PATCH v2 2/2] docs: Include simplified link titles in main index

[Carlos Bilbao]

Include simplified link titles in the main page's documentation index to
enhance website's readability and UX. Update the text that directs users to
various documents without changing the actual titles chosen by the authors.

Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
---
 Documentation/index.rst | 52 ++++++++++++++++++++---------------------
 1 file changed, 26 insertions(+), 26 deletions(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9dfdc826618c..5298611e00ee 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -22,10 +22,10 @@ community and getting your work upstream.
 .. toctree::
    :maxdepth: 1
 
-   process/development-process
-   process/submitting-patches
+   Development process <process/development-process>
+   Submitting patches <process/submitting-patches>
    Code of conduct <process/code-of-conduct>
-   maintainer/index
+   Maintainer handbook <maintainer/index>
    All development-process docs <process/index>
 
 
@@ -38,10 +38,10 @@ kernel.
 .. toctree::
    :maxdepth: 1
 
-   core-api/index
-   driver-api/index
-   subsystem-apis
-   Locking in the kernel <locking/index>
+   Core API <core-api/index>
+   Driver APIs <driver-api/index>
+   Subsystems <subsystem-apis>
+   Locking <locking/index>
 
 Development tools and processes
 ===============================
@@ -51,15 +51,15 @@ Various other manuals with useful information for all kernel developers.
 .. toctree::
    :maxdepth: 1
 
-   process/license-rules
-   doc-guide/index
-   dev-tools/index
-   dev-tools/testing-overview
-   kernel-hacking/index
-   trace/index
-   fault-injection/index
-   livepatch/index
-   rust/index
+   Licensing rules <process/license-rules>
+   Writing documentation <doc-guide/index>
+   Development tools <dev-tools/index>
+   Testing guide <dev-tools/testing-overview>
+   Hacking guide <kernel-hacking/index>
+   Tracing <trace/index>
+   Fault injection <fault-injection/index>
+   Livepatching <livepatch/index>
+   Rust <rust/index>
 
 
 User-oriented documentation
@@ -72,11 +72,11 @@ developers seeking information on the kernel's user-space APIs.
 .. toctree::
    :maxdepth: 1
 
-   admin-guide/index
-   The kernel build system <kbuild/index>
-   admin-guide/reporting-issues.rst
-   User-space tools <tools/index>
-   userspace-api/index
+   Administration <admin-guide/index>
+   Build system <kbuild/index>
+   Reporting issues <admin-guide/reporting-issues.rst>
+   Userspace tools <tools/index>
+   Userspace API <userspace-api/index>
 
 See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_,
 which are kept separately from the kernel's own documentation.
@@ -89,8 +89,8 @@ platform firmwares.
 .. toctree::
    :maxdepth: 1
 
-   firmware-guide/index
-   devicetree/index
+   Firmware <firmware-guide/index>
+   Firmware and Devicetree <devicetree/index>
 
 
 Architecture-specific documentation
@@ -99,7 +99,7 @@ Architecture-specific documentation
 .. toctree::
    :maxdepth: 2
 
-   arch/index
+   CPU architectures <arch/index>
 
 
 Other documentation
@@ -112,7 +112,7 @@ to ReStructured Text format, or are simply too old.
 .. toctree::
    :maxdepth: 1
 
-   staging/index
+   Unsorted documentation <staging/index>
 
 
 Translations
@@ -121,7 +121,7 @@ Translations
 .. toctree::
    :maxdepth: 2
 
-   translations/index
+   Translations <translations/index>
 
 Indices and tables
 ==================
-- 
2.34.1

Re: [PATCH v2 0/2] docs: Include simplified link titles in main index

[Carlos Bilbao]

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

Re: [PATCH v2 0/2] docs: Include simplified link titles in main index

[Jonathan Corbet]

Carlos Bilbao <carlos.bilbao@amd.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

Re: [PATCH v2 0/2] docs: Include simplified link titles in main index

[Carlos Bilbao]

On 2/21/24 14:40, Jonathan Corbet wrote:
> Carlos Bilbao <carlos.bilbao@amd.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.

 From my perspective, this improves readability for both the sidebar and
the main page, but I know that is a subjective perception. I look forward
to helping with alternative ways in the future.

> 
> Thanks,
> 
> jon

Thanks,
Carlos