diff mbox series

Documentation: index: Minor re-arrangement and improvements

Message ID 20240104073317.19709-1-d-gole@ti.com
State New
Headers
Series Documentation: index: Minor re-arrangement and improvements |

Commit Message

Dhruva Gole Jan. 4, 2024, 7:33 a.m. UTC 
  * It seems odd that a develper is forced to look at the licensing rules
  even before they get to the doc or coding guide.
  This belongs under the "Working with the development community" / "All
  development docs" page where it does reside even today.
* Rearrange the section for Internal API manuals to go lower because
  generally one would want to look at the tools and processes and admin
  guide pages first and then move onto something deeper like the API
  manuals.
* Reword the Dev tools section and title to something a bit more suitable.

Signed-off-by: Dhruva Gole <d-gole@ti.com>
---
 Documentation/index.rst | 34 ++++++++++++++++------------------
 1 file changed, 16 insertions(+), 18 deletions(-)


base-commit: d0b3c8aa5e37775cd7c3ac07b256218df0fd6678

Comments

Jonathan Corbet Jan. 23, 2024, 9:51 p.m. UTC | #1 
Dhruva Gole <d-gole@ti.com> writes:

> * It seems odd that a develper is forced to look at the licensing rules
>   even before they get to the doc or coding guide.
>   This belongs under the "Working with the development community" / "All
>   development docs" page where it does reside even today.
> * Rearrange the section for Internal API manuals to go lower because
>   generally one would want to look at the tools and processes and admin
>   guide pages first and then move onto something deeper like the API
>   manuals.
> * Reword the Dev tools section and title to something a bit more suitable.
>
> Signed-off-by: Dhruva Gole <d-gole@ti.com>

As a general rule, multiple items in the changelog like this suggest
that you need to break a patch up.

In this case, though, I guess I don't see the reason why we would want
to churn this page this way.  The ordering of the items on the front
page was thought through and discussed the last time we did this; why
should we revisit it now?

Thanks,

jon
Dhruva Gole Jan. 24, 2024, 6:21 a.m. UTC | #2 
On Jan 23, 2024 at 14:51:27 -0700, Jonathan Corbet wrote:
> Dhruva Gole <d-gole@ti.com> writes:
> 
> > * It seems odd that a develper is forced to look at the licensing rules
> >   even before they get to the doc or coding guide.
> >   This belongs under the "Working with the development community" / "All
> >   development docs" page where it does reside even today.
> > * Rearrange the section for Internal API manuals to go lower because
> >   generally one would want to look at the tools and processes and admin
> >   guide pages first and then move onto something deeper like the API
> >   manuals.
> > * Reword the Dev tools section and title to something a bit more suitable.
> >
> > Signed-off-by: Dhruva Gole <d-gole@ti.com>
> 
> As a general rule, multiple items in the changelog like this suggest
> that you need to break a patch up.

I understand, can break this patch up if required.

> 
> In this case, though, I guess I don't see the reason why we would want
> to churn this page this way.  The ordering of the items on the front
> page was thought through and discussed the last time we did this; why
> should we revisit it now?

The changes from "docs: Rewrite the front page[0]" are indeed great
however I saw a little more scope for improvement and thus decided to patch

Let me know how you think we should proceed.

[0] https://lore.kernel.org/r/20220927160559.97154-3-corbet@lwn.net

> 
> Thanks,
> 
> jon
diff mbox series

Patch

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 36e61783437c..409eba0b9601 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -28,30 +28,14 @@  community and getting your work upstream.
    maintainer/index
    All development-process docs <process/index>
 
-
-Internal API manuals
-====================
-
-Manuals for use by developers working to interface with the rest of the
-kernel.
-
-.. toctree::
-   :maxdepth: 1
-
-   core-api/index
-   driver-api/index
-   subsystem-apis
-   Locking in the kernel <locking/index>
-
-Development tools and processes
+Development tools and resources
 ===============================
 
-Various other manuals with useful information for all kernel developers.
+Various tools and manuals with useful information for all kernel developers.
 
 .. toctree::
    :maxdepth: 1
 
-   process/license-rules
    doc-guide/index
    dev-tools/index
    dev-tools/testing-overview
@@ -81,6 +65,20 @@  developers seeking information on the kernel's user-space APIs.
 See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_,
 which are kept separately from the kernel's own documentation.
 
+Internal API manuals
+====================
+
+Manuals for use by developers working to interface with the rest of the
+kernel.
+
+.. toctree::
+   :maxdepth: 1
+
+   core-api/index
+   driver-api/index
+   subsystem-apis
+   Locking in the kernel <locking/index>
+
 Firmware-related documentation
 ==============================
 The following holds information on the kernel's expectations regarding the