Re: [PATCH v3 2/7] docs: Rewrite the front page

From: Bagas Sanjaya
Date: Tue Sep 27 2022 - 23:32:52 EST


On 9/27/22 23:05, Jonathan Corbet wrote:
> The front page is the entry point to the documentation, especially for
> people who read it online. It's a big mess of everything we could think to
> toss into it. Rewrite the page with an eye toward simplicity and making it
> easy for readers to get going toward what they really want to find.
>
> This is only a beginning, but it makes our docs more approachable than
> before.
>
> Acked-by: Jani Nikula <jani.nikula@xxxxxxxxx>
> Reviewed-by: David Vernet <void@xxxxxxxxxxxxx>
> Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>
> ---
> Documentation/index.rst | 148 +++++++++++--------------------
> Documentation/subsystem-apis.rst | 58 ++++++++++++
> 2 files changed, 110 insertions(+), 96 deletions(-)
> create mode 100644 Documentation/subsystem-apis.rst
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 4737c18c97ff..bc492e79f1be 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -18,131 +18,88 @@ documents into a coherent whole. Please note that improvements to the
> documentation are welcome; join the linux-doc list at vger.kernel.org if
> you want to help out.
>
> -Licensing documentation
> ------------------------
> +Working with the development community
> +--------------------------------------
>
<snipped>...
> -User-oriented documentation
> ----------------------------
> -
> -The following manuals are written for *users* of the kernel — those who are
> -trying to get it to work optimally on a given system.
> +The essential guides for interacting with the kernel's development
> +community and getting your work upstream.
>
<snipped>...
> +User-oriented documentation
> +---------------------------
>
> -These books get into the details of how specific kernel subsystems work
> -from the point of view of a kernel developer. Much of the information here
> -is taken directly from the kernel source, with supplemental material added
> -as needed (or at least as we managed to add it — probably *not* all that is
> -needed).
> +The following manuals are written for *users* of the kernel — those who are
> +trying to get it to work optimally on a given system and application
> +developers seeking information on the kernel's user-space APIs.
>
> .. toctree::
> - :maxdepth: 2
> + :maxdepth: 1
> +
> + admin-guide/index
> + The kernel build system <kbuild/index>
> + admin-guide/reporting-issues.rst
> + User-space tools <tools/index>
> + userspace-api/index
> +

Hi jon,

Why did developer documentations list first before user-oriented ones? I looked
the rendered result as if the former was given more spotlight than the latter.

Thanks.

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