[PATCH 0/3] docs: organize the admin guide

[PATCH 0/3] docs: organize the admin guide

[Jonathan Corbet]

Our documentation directories inevitably turn into an unorganized
pile of material that is less than friendly to our users; that has
happened with the admin guide.  Reorganize the index.rst file to make
it easier to find the material of interest.

The rendered version of the reworked guide can be viewed at:

  https://static.lwn.net/kerneldoc/admin-guide/

I've not done anything to update or weed out any of the documents
found here, which would be a great next step.  When you have, say, a
document describing how to partition your 50MB disk (ldm.rst), that's
a sign that the cobwebs have started to build up.

Jonathan Corbet (3):
  docs: admin-guide: join the sysfs information in one place
  docs: admin-guide: add some subsection headings
  docs: admin-guide: bring some order to the "everything else" section

 Documentation/admin-guide/index.rst | 163 ++++++++++++++++++----------
 1 file changed, 108 insertions(+), 55 deletions(-)

-- 
2.47.1

[PATCH 1/3] docs: admin-guide: join the sysfs information in one place

[Jonathan Corbet]

The documents describing sysfs are spread out in the admin guide; bring
them together in one place.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/admin-guide/index.rst | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 15a522a96e76..94b70bb203cc 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -19,7 +19,6 @@ etc.
    devices
    sysctl/index
 
-   abi
    features
 
 This section describes CPU vulnerabilities and their mitigations.
@@ -49,14 +48,14 @@ problems and bugs in particular.
    perf/index
    pstore-blk
 
-This is the beginning of a section with information of interest to
-application developers.  Documents covering various aspects of the kernel
-ABI will be found here.
+A big part of the kernel's administrative interface is the sysfs virtual
+filesystem; these documents describe how to interact with sysfs.
 
 .. toctree::
    :maxdepth: 1
 
    sysfs-rules
+   abi
 
 This is the beginning of a section with information of interest to
 application developers and system integrators doing analysis of the
-- 
2.47.1

Re: [PATCH 1/3] docs: admin-guide: join the sysfs information in one place

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 314 bytes --]

On Fri, Dec 13, 2024 at 11:20:52AM -0700, Jonathan Corbet wrote:
> The documents describing sysfs are spread out in the admin guide; bring
> them together in one place.
> 

Looks good, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 1/3] docs: admin-guide: join the sysfs information in one place

[Randy Dunlap]

On 12/13/24 10:20 AM, Jonathan Corbet wrote:
> The documents describing sysfs are spread out in the admin guide; bring
> them together in one place.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/admin-guide/index.rst | 7 +++----
>  1 file changed, 3 insertions(+), 4 deletions(-)
> 

Looks good. Thanks.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy

[PATCH 2/3] docs: admin-guide: add some subsection headings

[Jonathan Corbet]

As part of the goal of bringing some order to this file, add subsection
headings to help readers find what they are looking for.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/admin-guide/index.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 94b70bb203cc..6864b079b391 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -7,6 +7,9 @@ added to the kernel over time.  There is, as yet, little overall order or
 organization here — this material was not written to be a single, coherent
 document!  With luck things will improve quickly over time.
 
+General guides to kernel administration
+---------------------------------------
+
 This initial section contains overall information, including the README
 file describing the kernel as a whole, documentation on kernel parameters,
 etc.
@@ -28,6 +31,9 @@ This section describes CPU vulnerabilities and their mitigations.
 
    hw-vuln/index
 
+Tracking down and identifying problems
+--------------------------------------
+
 Here is a set of documents aimed at users who are trying to track down
 problems and bugs in particular.
 
@@ -48,6 +54,9 @@ problems and bugs in particular.
    perf/index
    pstore-blk
 
+sysfs
+-----
+
 A big part of the kernel's administrative interface is the sysfs virtual
 filesystem; these documents describe how to interact with sysfs.
 
@@ -57,6 +66,9 @@ filesystem; these documents describe how to interact with sysfs.
    sysfs-rules
    abi
 
+Workload analysis
+-----------------
+
 This is the beginning of a section with information of interest to
 application developers and system integrators doing analysis of the
 Linux kernel for safety critical applications. Documents supporting
@@ -68,6 +80,9 @@ subsystems expectations will be found here.
 
    workload-tracing
 
+Everything else
+---------------
+
 The rest of this manual consists of various unordered guides on how to
 configure specific aspects of kernel behavior to your liking.
 
-- 
2.47.1

Re: [PATCH 2/3] docs: admin-guide: add some subsection headings

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 339 bytes --]

On Fri, Dec 13, 2024 at 11:20:53AM -0700, Jonathan Corbet wrote:
> As part of the goal of bringing some order to this file, add subsection
> headings to help readers find what they are looking for.

Looks good, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 2/3] docs: admin-guide: add some subsection headings

[Randy Dunlap]

On 12/13/24 10:20 AM, Jonathan Corbet wrote:
> As part of the goal of bringing some order to this file, add subsection
> headings to help readers find what they are looking for.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/admin-guide/index.rst | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

-- 
~Randy

[PATCH 3/3] docs: admin-guide: bring some order to the "everything else" section

[Jonathan Corbet]

The bulk of the admin guide had become a big pile of stuff haphazardly
tossed together, mostly in the catch-all "everything else" section.  Split
that section into a few broad categories and sort the documents into them
as appropriate.

No documents have been added or removed, they are just reordered.  Note
that many of these documents are severely obsolete and should be considered
for removal.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/admin-guide/index.rst | 161 +++++++++++++++++-----------
 1 file changed, 100 insertions(+), 61 deletions(-)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 6864b079b391..c8af32a8f800 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -18,18 +18,41 @@ etc.
    :maxdepth: 1
 
    README
-   kernel-parameters
    devices
-   sysctl/index
 
    features
 
-This section describes CPU vulnerabilities and their mitigations.
+A big part of the kernel's administrative interface is the /proc and sysfs
+virtual filesystems; these documents describe how to interact with tem
+
+.. toctree::
+   :maxdepth: 1
+
+   sysfs-rules
+   sysctl/index
+   cputopology
+   abi
+
+Security-related documentation:
 
 .. toctree::
    :maxdepth: 1
 
    hw-vuln/index
+   LSM/index
+   perf-security
+
+Booting the kernel
+------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   bootconfig
+   kernel-parameters
+   efi-stub
+   initrd
+
 
 Tracking down and identifying problems
 --------------------------------------
@@ -53,104 +76,120 @@ problems and bugs in particular.
    kdump/index
    perf/index
    pstore-blk
+   clearing-warn-once
+   kernel-per-CPU-kthreads
+   lockup-watchdogs
+   RAS/index
+   sysrq
+
 
-sysfs
------
+Core-kernel subsystems
+----------------------
 
-A big part of the kernel's administrative interface is the sysfs virtual
-filesystem; these documents describe how to interact with sysfs.
+These documents describe core-kernel administration interfaces that are
+likely to be of interest on almost any system.
 
 .. toctree::
    :maxdepth: 1
 
-   sysfs-rules
-   abi
-
-Workload analysis
------------------
+   cgroup-v2
+   cgroup-v1/index
+   cpu-load
+   mm/index
+   module-signing
+   namespaces/index
+   numastat
+   pm/index
+   syscall-user-dispatch
 
-This is the beginning of a section with information of interest to
-application developers and system integrators doing analysis of the
-Linux kernel for safety critical applications. Documents supporting
-analysis of kernel interactions with applications, and key kernel
-subsystems expectations will be found here.
+Support for non-native binary formats.  Note that some of these
+documents are ... old ...
 
 .. toctree::
    :maxdepth: 1
 
-   workload-tracing
+   binfmt-misc
+   java
+   mono
 
-Everything else
----------------
 
-The rest of this manual consists of various unordered guides on how to
-configure specific aspects of kernel behavior to your liking.
+Block-layer and filesystem administration
+-----------------------------------------
 
 .. toctree::
    :maxdepth: 1
 
-   acpi/index
-   aoe/index
-   auxdisplay/index
    bcache
    binderfs
-   binfmt-misc
    blockdev/index
-   bootconfig
-   braille-console
-   btmrvl
-   cgroup-v1/index
-   cgroup-v2
    cifs/index
-   clearing-warn-once
-   cpu-load
-   cputopology
-   dell_rbu
    device-mapper/index
-   edid
-   efi-stub
    ext4
    filesystem-monitoring
    nfs/index
-   gpio/index
-   highuid
-   hw_random
-   initrd
    iostats
-   java
    jfs
-   kernel-per-CPU-kthreads
+   md
+   ufs
+   xfs
+
+Device-specific guides
+----------------------
+
+How to configure your hardware within your Linux system.
+
+.. toctree::
+   :maxdepth: 1
+
+   acpi/index
+   aoe/index
+   auxdisplay/index
+   braille-console
+   btmrvl
+   dell_rbu
+   edid
+   gpio/index
+   hw_random
    laptops/index
    lcd-panel-cgram
-   ldm
-   lockup-watchdogs
-   LSM/index
-   md
    media/index
-   mm/index
-   module-signing
-   mono
-   namespaces/index
-   numastat
+   nvme-multipath
    parport
-   perf-security
-   pm/index
    pnp
    rapidio
-   RAS/index
    rtc
    serial-console
    svga
-   syscall-user-dispatch
-   sysrq
    thermal/index
    thunderbolt
-   ufs
-   unicode
    vga-softcursor
    video-output
-   xfs
-   nvme-multipath
+
+Workload analysis
+-----------------
+
+This is the beginning of a section with information of interest to
+application developers and system integrators doing analysis of the
+Linux kernel for safety critical applications. Documents supporting
+analysis of kernel interactions with applications, and key kernel
+subsystems expectations will be found here.
+
+.. toctree::
+   :maxdepth: 1
+
+   workload-tracing
+
+Everything else
+---------------
+
+A few hard-to-categorize and generally obsolete documents.
+
+.. toctree::
+   :maxdepth: 1
+
+   highuid
+   ldm
+   unicode
 
 .. only::  subproject and html
 
-- 
2.47.1

Re: [PATCH 3/3] docs: admin-guide: bring some order to the "everything else" section

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 5376 bytes --]

On Fri, Dec 13, 2024 at 11:20:54AM -0700, Jonathan Corbet wrote:
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 6864b079b391..c8af32a8f800 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -18,18 +18,41 @@ etc.
>     :maxdepth: 1
>  
>     README
> -   kernel-parameters
>     devices
> -   sysctl/index
>  
>     features
>  
> -This section describes CPU vulnerabilities and their mitigations.
> +A big part of the kernel's administrative interface is the /proc and sysfs
> +virtual filesystems; these documents describe how to interact with tem
                                                                     "them"
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   sysfs-rules
> +   sysctl/index
> +   cputopology
> +   abi
> +
> +Security-related documentation:
>  
>  .. toctree::
>     :maxdepth: 1
>  
>     hw-vuln/index
> +   LSM/index
> +   perf-security
> +
> +Booting the kernel
> +------------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   bootconfig
> +   kernel-parameters
> +   efi-stub
> +   initrd
> +
>  
>  Tracking down and identifying problems
>  --------------------------------------
> @@ -53,104 +76,120 @@ problems and bugs in particular.
>     kdump/index
>     perf/index
>     pstore-blk
> +   clearing-warn-once
> +   kernel-per-CPU-kthreads
> +   lockup-watchdogs
> +   RAS/index
> +   sysrq
> +
>  
> -sysfs
> ------
> +Core-kernel subsystems
> +----------------------
>  
> -A big part of the kernel's administrative interface is the sysfs virtual
> -filesystem; these documents describe how to interact with sysfs.
> +These documents describe core-kernel administration interfaces that are
> +likely to be of interest on almost any system.
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   sysfs-rules
> -   abi
> -
> -Workload analysis
> ------------------
> +   cgroup-v2
> +   cgroup-v1/index
> +   cpu-load
> +   mm/index
> +   module-signing
> +   namespaces/index
> +   numastat
> +   pm/index
> +   syscall-user-dispatch
>  
> -This is the beginning of a section with information of interest to
> -application developers and system integrators doing analysis of the
> -Linux kernel for safety critical applications. Documents supporting
> -analysis of kernel interactions with applications, and key kernel
> -subsystems expectations will be found here.
> +Support for non-native binary formats.  Note that some of these
> +documents are ... old ...
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   workload-tracing
> +   binfmt-misc
> +   java
> +   mono
>  
> -Everything else
> ----------------
>  
> -The rest of this manual consists of various unordered guides on how to
> -configure specific aspects of kernel behavior to your liking.
> +Block-layer and filesystem administration
> +-----------------------------------------
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   acpi/index
> -   aoe/index
> -   auxdisplay/index
>     bcache
>     binderfs
> -   binfmt-misc
>     blockdev/index
> -   bootconfig
> -   braille-console
> -   btmrvl
> -   cgroup-v1/index
> -   cgroup-v2
>     cifs/index
> -   clearing-warn-once
> -   cpu-load
> -   cputopology
> -   dell_rbu
>     device-mapper/index
> -   edid
> -   efi-stub
>     ext4
>     filesystem-monitoring
>     nfs/index
> -   gpio/index
> -   highuid
> -   hw_random
> -   initrd
>     iostats
> -   java
>     jfs
> -   kernel-per-CPU-kthreads
> +   md
> +   ufs
> +   xfs
> +
> +Device-specific guides
> +----------------------
> +
> +How to configure your hardware within your Linux system.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   acpi/index
> +   aoe/index
> +   auxdisplay/index
> +   braille-console
> +   btmrvl
> +   dell_rbu
> +   edid
> +   gpio/index
> +   hw_random
>     laptops/index
>     lcd-panel-cgram
> -   ldm
> -   lockup-watchdogs
> -   LSM/index
> -   md
>     media/index
> -   mm/index
> -   module-signing
> -   mono
> -   namespaces/index
> -   numastat
> +   nvme-multipath
>     parport
> -   perf-security
> -   pm/index
>     pnp
>     rapidio
> -   RAS/index
>     rtc
>     serial-console
>     svga
> -   syscall-user-dispatch
> -   sysrq
>     thermal/index
>     thunderbolt
> -   ufs
> -   unicode
>     vga-softcursor
>     video-output
> -   xfs
> -   nvme-multipath
> +
> +Workload analysis
> +-----------------
> +
> +This is the beginning of a section with information of interest to
> +application developers and system integrators doing analysis of the
> +Linux kernel for safety critical applications. Documents supporting
> +analysis of kernel interactions with applications, and key kernel
> +subsystems expectations will be found here.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   workload-tracing
> +
> +Everything else
> +---------------
> +
> +A few hard-to-categorize and generally obsolete documents.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   highuid
> +   ldm
> +   unicode
>  
>  .. only::  subproject and html
>  

The rest looks good.

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 3/3] docs: admin-guide: bring some order to the "everything else" section

[Randy Dunlap]

On 12/13/24 10:20 AM, Jonathan Corbet wrote:
> The bulk of the admin guide had become a big pile of stuff haphazardly
> tossed together, mostly in the catch-all "everything else" section.  Split
> that section into a few broad categories and sort the documents into them
> as appropriate.
> 
> No documents have been added or removed, they are just reordered.  Note
> that many of these documents are severely obsolete and should be considered
> for removal.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/admin-guide/index.rst | 161 +++++++++++++++++-----------
>  1 file changed, 100 insertions(+), 61 deletions(-)
> 

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

-- 
~Randy