[PATCH] docs: reorganize kernel documentation overview for clarity

[PATCH] docs: reorganize kernel documentation overview for clarity

[Mr Tourist]

[-- Attachment #1.1: Type: text/plain, Size: 616 bytes --]

Date: Wed,  1 Oct 2025 11:18:07 +0000
Message-ID: <20251001111807.7900-1-zakiuddin321@gmail.com>
X-Mailer: git-send-email 2.50.1
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

    The Cc list above has been expanded by additional
    addresses found in the patch commit message. By default
    send-email prompts before sending whenever this occurs.
    This behavior is controlled by the sendemail.confirm
    configuration setting.

    For additional information, run 'git send-email --help'.
    To retain the current behavior, but squelch this message,
    run 'git config --global sendemail.confirm auto'.

[-- Attachment #1.2: Type: text/html, Size: 785 bytes --]

[-- Attachment #2: 0001-docs-reorganize-kernel-documentation-overview-for-cl.patch --]
[-- Type: application/octet-stream, Size: 2919 bytes --]

From a3d1ab33cc3166006fc553a1da32e1e9cb65a2e4 Mon Sep 17 00:00:00 2001
From: Mohammed Zakiuddin <zakiuddin321@gmail.com>
Date: Wed, 1 Oct 2025 11:09:14 +0000
Subject: [PATCH] docs: reorganize kernel documentation overview for clarity

Restructure the kernel documentation overview to improve readability and
accessibility. Changes include:

- Add clear hierarchical sections with descriptive headers
- Organized content into logical groupings
- Improve formatting for better visual scanning
- Maintain all existing information while presenting it more
  systematically

The revised structure helps new users and developers to navigate the
kernel documentation system in a better way

Signed-off-by: Mohammed Zakiuddin <zakiuddin321@gmail.com>
---
 README    | 18 ------------------
 README.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 18 deletions(-)
 delete mode 100644 README
 create mode 100644 README.md

diff --git a/README b/README
deleted file mode 100644
index fd903645e6de..000000000000
--- a/README
+++ /dev/null
@@ -1,18 +0,0 @@
-Linux kernel
-============
-
-There are several guides for kernel developers and users. These guides can
-be rendered in a number of formats, like HTML and PDF. Please read
-Documentation/admin-guide/README.rst first.
-
-In order to build the documentation, use ``make htmldocs`` or
-``make pdfdocs``.  The formatted documentation can also be read online at:
-
-    https://www.kernel.org/doc/html/latest/
-
-There are various text files in the Documentation/ subdirectory,
-several of them using the reStructuredText markup notation.
-
-Please read the Documentation/process/changes.rst file, as it contains the
-requirements for building and running the kernel, and information about
-the problems which may result by upgrading your kernel.
diff --git a/README.md b/README.md
new file mode 100644
index 000000000000..a2c9b69b67fd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,28 @@
+# Linux kernel
+
+## Documentation Overview
+The Linux kernel documentation is available in multiple formats(HTML, PDF) and contains essentail guides for both developers and users.
+
+## Key Documentation
+
+### Primary Starting Point
+- Documentation/admin-guide/README.rst
+
+### Building Documentation
+- For HTML: `make htmldocs`
+- For PDF: `make pdfdocs`
+
+### Online Access
+- Official documentation: https://www.kernel.org/doc/html/latest/
+
+## Important Notes
+- Documentation is primarily located in the Documentaion/ directory
+- Manuy files use reStructuredText format
+- Before kernel upgrades or builds, review Documentation /process/changes.rst for
+    * Build Requirements
+    * Runtime requirements
+    * Potential upgrade issues and solutions 
+There are several guides for kernel developers and users. These guides can
+be rendered in a number of formats, like HTML and PDF. Please read
+Documentation/admin-guide/README.rst first.
+
-- 
2.50.1

Re: [PATCH] docs: reorganize kernel documentation overview for clarity

[Randy Dunlap]

Hi Mr,

On 10/1/25 4:20 AM, Mr Tourist wrote:
> Date: Wed,  1 Oct 2025 11:18:07 +0000
> Message-ID: <20251001111807.7900-1-zakiuddin321@gmail.com <mailto:20251001111807.7900-1-zakiuddin321@gmail.com>>
> X-Mailer: git-send-email 2.50.1
> MIME-Version: 1.0
> Content-Transfer-Encoding: 8bit
> 
>     The Cc list above has been expanded by additional
>     addresses found in the patch commit message. By default
>     send-email prompts before sending whenever this occurs.
>     This behavior is controlled by the sendemail.confirm
>     configuration setting.
> 
>     For additional information, run 'git send-email --help'.
>     To retain the current behavior, but squelch this message,
>     run 'git config --global sendemail.confirm auto'.

Eh?


You failed to say why converting README to README.md is a good thing
or why it's needed.
What should I do with a markdown file? I'm just trying to read it
like it's a text file.


The bullet/outline format is good IMO, but that couldn't that be done
in the original README file?


Minor stuff:

Warning: trailing whitespace in line 24 of README.md


Thanks.
-- 
~Randy

Re: [PATCH] docs: reorganize kernel documentation overview for clarity

[Matthew Wilcox]

On Wed, Oct 01, 2025 at 04:50:52PM +0530, Mr Tourist wrote:

... you screwed up sending this, so I can't reply to it properly.

But in general, Linux uses reStructuredText, not Markdown.

Re: [PATCH] docs: reorganize kernel documentation overview for clarity

[Mr Tourist]

[-- Attachment #1.1: Type: text/plain, Size: 504 bytes --]

Thanks for the review and comments provided Matthew and Randy,

I have addressed the comments shared and have attached the updated patch
over the email.

Message-ID: <20251002041325.6406-1-zakiuddin321@gmail.com>

On Thu, Oct 2, 2025 at 6:42 AM Matthew Wilcox <willy@infradead.org> wrote:

> On Wed, Oct 01, 2025 at 04:50:52PM +0530, Mr Tourist wrote:
>
> ... you screwed up sending this, so I can't reply to it properly.
>
> But in general, Linux uses reStructuredText, not Markdown.
>

[-- Attachment #1.2: Type: text/html, Size: 929 bytes --]

[-- Attachment #2: 0001-docs-rename-README-to-README.rst-and-improve-structu.patch --]
[-- Type: application/octet-stream, Size: 3343 bytes --]

From fd7d48cfc89a73f9721c8a2f69b509c4ded29fab Mon Sep 17 00:00:00 2001
From: Mohammed Zakiuddin <zakiuddin321@gmail.com>
Date: Thu, 2 Oct 2025 04:07:05 +0000
Subject: [PATCH] docs: rename README to README.rst and improve structure

Renamed README to README.rst to explicitly indicate its reStruturedText
format and improve its structure. This is done to follow the same format
as put in the documentation for other things.

Below are the changes made:
- Renames README to README.rst to match the actual format
- Makes the file format clear to readers and editors
- Aligns with documentation standards where .rst extension is used for
  reStructuredText files throughout the kernel
- Improvves structure with clear hierarchical sections
- Organizes content into logical groupings

The .rst extension helps tools and editors provide proper syntax
highlighting and formatting support, making it easier to preview the
changes.

Signed-off-by: Mohammed Zakiuddin <zakiuddin321@gmail.com>
---
 README.md  | 28 ----------------------------
 README.rst | 31 +++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 28 deletions(-)
 delete mode 100644 README.md
 create mode 100644 README.rst

diff --git a/README.md b/README.md
deleted file mode 100644
index a2c9b69b67fd..000000000000
--- a/README.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Linux kernel
-
-## Documentation Overview
-The Linux kernel documentation is available in multiple formats(HTML, PDF) and contains essentail guides for both developers and users.
-
-## Key Documentation
-
-### Primary Starting Point
-- Documentation/admin-guide/README.rst
-
-### Building Documentation
-- For HTML: `make htmldocs`
-- For PDF: `make pdfdocs`
-
-### Online Access
-- Official documentation: https://www.kernel.org/doc/html/latest/
-
-## Important Notes
-- Documentation is primarily located in the Documentaion/ directory
-- Manuy files use reStructuredText format
-- Before kernel upgrades or builds, review Documentation /process/changes.rst for
-    * Build Requirements
-    * Runtime requirements
-    * Potential upgrade issues and solutions 
-There are several guides for kernel developers and users. These guides can
-be rendered in a number of formats, like HTML and PDF. Please read
-Documentation/admin-guide/README.rst first.
-
diff --git a/README.rst b/README.rst
new file mode 100644
index 000000000000..7cc594d13347
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,31 @@
+Linux Kernel
+===========
+
+Documentation Overview
+--------------------
+The Linux kernel documentation is available in multiple formats (HTML, PDF) and contains essential guides for both developers and users.
+
+Key Documentation
+---------------
+
+Primary Starting Point
+~~~~~~~~~~~~~~~~~~~~
+* Documentation/admin-guide/README.rst
+
+Building Documentation
+~~~~~~~~~~~~~~~~~~~~
+* For HTML: ``make htmldocs``
+* For PDF: ``make pdfdocs``
+
+Online Access
+~~~~~~~~~~~~
+* Official documentation: https://www.kernel.org/doc/html/latest/
+
+Important Notes
+-------------
+* Documentation is primarily located in the Documentation/ directory
+* Files use reStructuredText format
+* Before kernel upgrades or builds, review Documentation/process/changes.rst for:
+    - Build requirements
+    - Runtime requirements
+    - Potential upgrade issues and solutions
\ No newline at end of file
-- 
2.50.1

Re: [PATCH] docs: reorganize kernel documentation overview for clarity

[Matthew Wilcox]

On Thu, Oct 02, 2025 at 09:46:26AM +0530, Mr Tourist wrote:
> Thanks for the review and comments provided Matthew and Randy,
> 
> I have addressed the comments shared and have attached the updated patch
> over the email.

No, send the patch inline.

Also generate the patch relative to what is currently in the tree,
not relative to the last patch you sent.

Re: [PATCH] docs: reorganize kernel documentation overview for clarity

[Bagas Sanjaya]

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

On Thu, Oct 02, 2025 at 01:23:23PM +0100, Matthew Wilcox wrote:
> On Thu, Oct 02, 2025 at 09:46:26AM +0530, Mr Tourist wrote:
> > Thanks for the review and comments provided Matthew and Randy,
> > 
> > I have addressed the comments shared and have attached the updated patch
> > over the email.
> 
> No, send the patch inline.
> 
> Also generate the patch relative to what is currently in the tree,
> not relative to the last patch you sent.
> 

tl;dr: see Documentation/process/submitting-patches.rst.

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

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

Re: [PATCH] docs: reorganize kernel documentation overview for clarity

[Jonathan Corbet]

Matthew Wilcox <willy@infradead.org> writes:

> On Thu, Oct 02, 2025 at 09:46:26AM +0530, Mr Tourist wrote:
>> Thanks for the review and comments provided Matthew and Randy,
>> 
>> I have addressed the comments shared and have attached the updated patch
>> over the email.
>
> No, send the patch inline.
>
> Also generate the patch relative to what is currently in the tree,
> not relative to the last patch you sent.

...also, copying the documentation maintainer would be a good thing to
do...

Thanks,

jon