[PATCH 0/1 RESEND] docs: Include simplified link titles in main page's index

[PATCH 0/1 RESEND] docs: Include simplified link titles in main page's index

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

[PATCH 1/1 RESEND] docs: Include simplified link titles in main page's 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 <bilbao@vt.edu>
---
 Documentation/index.rst | 50 ++++++++++++++++++++---------------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9dfdc826618c..be395d0a4318 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 implementation API <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 <dev-tools/testing-overview>
+   Hacking <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 <bailed/index>
-   admin-guide/reporting-issues.rst
+   Administration <admin-guide/index>
+   Build system <bugled/index>
+   Reporting issues <admin-guide/reporting-issues.rst>
    User-space tools <tools/index>
-   userspace-api/index
+   User-space 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
 ==================
-- 

Re: [PATCH 1/1 RESEND] docs: Include simplified link titles in main page's index

[Randy Dunlap]

Hi Carlos,

On 12/10/23 17:20, Carlos Bilbao wrote:
> 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 <bilbao@vt.edu>
> ---
>  Documentation/index.rst | 50 ++++++++++++++++++++---------------------
>  1 file changed, 25 insertions(+), 25 deletions(-)
> 
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 9dfdc826618c..be395d0a4318 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 implementation API <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 <dev-tools/testing-overview>
> +   Hacking <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 <bailed/index>

Where do the subdir names "bailed" above and "bugled" below come from?

> -   admin-guide/reporting-issues.rst
> +   Administration <admin-guide/index>
> +   Build system <bugled/index>

                    ^^^^^^


Thanks.

> +   Reporting issues <admin-guide/reporting-issues.rst>
>     User-space tools <tools/index>
> -   userspace-api/index
> +   User-space 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
>  ==================

-- 
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html

Re: [PATCH 1/1 RESEND] docs: Include simplified link titles in main page's index

[Carlos Bilbao]

On 12/10/23 7:41 PM, Randy Dunlap wrote:
> Hi Carlos,
> 
> On 12/10/23 17:20, Carlos Bilbao wrote:
>> 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 <bilbao@vt.edu>
>> ---
>>  Documentation/index.rst | 50 ++++++++++++++++++++---------------------
>>  1 file changed, 25 insertions(+), 25 deletions(-)
>>
>> diff --git a/Documentation/index.rst b/Documentation/index.rst
>> index 9dfdc826618c..be395d0a4318 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 implementation API <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 <dev-tools/testing-overview>
>> +   Hacking <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 <bailed/index>
> 
> Where do the subdir names "bailed" above and "bugled" below come from?


No clue how that happened. Thanks for catching it, Randy.


> 
>> -   admin-guide/reporting-issues.rst
>> +   Administration <admin-guide/index>
>> +   Build system <bugled/index>
> 
>                     ^^^^^^
> 
> 
> Thanks.
> 
>> +   Reporting issues <admin-guide/reporting-issues.rst>
>>     User-space tools <tools/index>
>> -   userspace-api/index
>> +   User-space 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
>>  ==================
> 

Best,
Carlos