[PATCH] docs: improve formatting and readability of the main README

[PATCH] docs: improve formatting and readability of the main README

[Darío Ortega Leyva]

Restructured the main documentation file to use standard Markdown 
headings instead of underlines for better rendering. Added anchor links 
to the "Who Are You?" section to improve navigability for new readers, 
and highlighted the AI Assistant warning for better visibility.

Signed-off-by: Darío Ortega Leyva <darioortegaleyva@gmail.com>
Signed-off-by: Dario Ortega Leyva <darioortegaleyva@gmail.com>
---
  README | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 143 insertions(+)
  create mode 100644 README

diff --git a/README b/README
new file mode 100644
index 000000000..bc2ce650c
--- /dev/null
+++ b/README
@@ -0,0 +1,143 @@
+# Linux Kernel
+
+The Linux kernel is the core of any Linux operating system. It manages 
hardware, system resources, and provides the fundamental services for 
all other software.
+
+## Quick Start
+
+* **Report a bug:** See `Documentation/admin-guide/reporting-issues.rst`
+* **Get the latest kernel:** Visit [kernel.org](https://kernel.org)
+* **Build the kernel:** See 
`Documentation/admin-guide/quickly-build-trimmed-linux.rst`
+* **Join the community:** Visit [lore.kernel.org](https://lore.kernel.org/)
+
+## Essential Documentation
+
+All users should be familiar with the following core documents:
+
+* **Building requirements:** `Documentation/process/changes.rst`
+* **Code of Conduct:** `Documentation/process/code-of-conduct.rst`
+* **License:** See the `COPYING` file.
+
+> **Note:** Documentation can be built locally with `make htmldocs` or 
viewed online at 
[kernel.org/doc/html/latest/](https://www.kernel.org/doc/html/latest/).
+
+---
+
+## Who Are You?
+
+Find your role below to jump to the most relevant resources:
+
+* [New Kernel Developer](#new-kernel-developer) - Getting started with 
kernel development
+* [Academic Researcher](#academic-researcher) - Studying kernel 
internals and architecture
+* [Security Expert](#security-expert) - Hardening and vulnerability 
analysis
+* [Backport/Maintenance Engineer](#backportmaintenance-engineer) - 
Maintaining stable kernels
+* [System Administrator](#system-administrator) - Configuring and 
troubleshooting
+* [Maintainer](#maintainer) - Leading subsystems and reviewing patches
+* [Hardware Vendor](#hardware-vendor) - Writing drivers for new hardware
+* [Distribution Maintainer](#distribution-maintainer) - Packaging 
kernels for distros
+* [AI Coding Assistant](#ai-coding-assistant) - LLMs and AI-powered 
development tools
+
+---
+
+## For Specific Users
+
+### New Kernel Developer
+Welcome! Start your kernel development journey here:
+
+* **Getting Started:** `Documentation/process/development-process.rst`
+* **Your First Patch:** `Documentation/process/submitting-patches.rst`
+* **Coding Style:** `Documentation/process/coding-style.rst`
+* **Build System:** `Documentation/kbuild/index.rst`
+* **Development Tools:** `Documentation/dev-tools/index.rst`
+* **Kernel Hacking Guide:** `Documentation/kernel-hacking/hacking.rst`
+* **Core APIs:** `Documentation/core-api/index.rst`
+
+### Academic Researcher
+Explore the kernel's architecture and internals:
+
+* **Researcher Guidelines:** 
`Documentation/process/researcher-guidelines.rst`
+* **Memory Management:** `Documentation/mm/index.rst`
+* **Scheduler:** `Documentation/scheduler/index.rst`
+* **Networking Stack:** `Documentation/networking/index.rst`
+* **Filesystems:** `Documentation/filesystems/index.rst`
+* **RCU (Read-Copy Update):** `Documentation/RCU/index.rst`
+* **Locking Primitives:** `Documentation/locking/index.rst`
+* **Power Management:** `Documentation/power/index.rst`
+
+### Security Expert
+Security documentation and hardening guides:
+
+* **Security Documentation:** `Documentation/security/index.rst`
+* **LSM Development:** `Documentation/security/lsm-development.rst`
+* **Self Protection:** `Documentation/security/self-protection.rst`
+* **Reporting Vulnerabilities:** `Documentation/process/security-bugs.rst`
+* **CVE Procedures:** `Documentation/process/cve.rst`
+* **Embargoed Hardware Issues:** 
`Documentation/process/embargoed-hardware-issues.rst`
+* **Security Features:** `Documentation/userspace-api/seccomp_filter.rst`
+
+### Backport/Maintenance Engineer
+Maintain and stabilize kernel versions:
+
+* **Stable Kernel Rules:** `Documentation/process/stable-kernel-rules.rst`
+* **Backporting Guide:** `Documentation/process/backporting.rst`
+* **Applying Patches:** `Documentation/process/applying-patches.rst`
+* **Subsystem Profile:** 
`Documentation/maintainer/maintainer-entry-profile.rst`
+* **Git for Maintainers:** `Documentation/maintainer/configure-git.rst`
+
+### System Administrator
+Configure, tune, and troubleshoot Linux systems:
+
+* **Admin Guide:** `Documentation/admin-guide/index.rst`
+* **Kernel Parameters:** `Documentation/admin-guide/kernel-parameters.rst`
+* **Sysctl Tuning:** `Documentation/admin-guide/sysctl/index.rst`
+* **Tracing/Debugging:** `Documentation/trace/index.rst`
+* **Performance Security:** `Documentation/admin-guide/perf-security.rst`
+* **Hardware Monitoring:** `Documentation/hwmon/index.rst`
+
+### Maintainer
+Lead kernel subsystems and manage contributions:
+
+* **Maintainer Handbook:** `Documentation/maintainer/index.rst`
+* **Pull Requests:** `Documentation/maintainer/pull-requests.rst`
+* **Managing Patches:** `Documentation/maintainer/modifying-patches.rst`
+* **Rebasing and Merging:** 
`Documentation/maintainer/rebasing-and-merging.rst`
+* **Development Process:** `Documentation/process/maintainer-handbooks.rst`
+* **Maintainer Entry Profile:** 
`Documentation/maintainer/maintainer-entry-profile.rst`
+* **Git Configuration:** `Documentation/maintainer/configure-git.rst`
+
+### Hardware Vendor
+Write drivers and support new hardware:
+
+* **Driver API Guide:** `Documentation/driver-api/index.rst`
+* **Driver Model:** `Documentation/driver-api/driver-model/driver.rst`
+* **Device Drivers:** `Documentation/driver-api/infrastructure.rst`
+* **Bus Types:** `Documentation/driver-api/driver-model/bus.rst`
+* **Device Tree Bindings:** `Documentation/devicetree/bindings/`
+* **Power Management:** `Documentation/driver-api/pm/index.rst`
+* **DMA API:** `Documentation/core-api/dma-api.rst`
+
+### Distribution Maintainer
+Package and distribute the kernel:
+
+* **Stable Kernel Rules:** `Documentation/process/stable-kernel-rules.rst`
+* **ABI Documentation:** `Documentation/ABI/README`
+* **Kernel Configuration:** `Documentation/kbuild/kconfig.rst`
+* **Module Signing:** `Documentation/admin-guide/module-signing.rst`
+* **Kernel Parameters:** `Documentation/admin-guide/kernel-parameters.rst`
+* **Tainted Kernels:** `Documentation/admin-guide/tainted-kernels.rst`
+
+### AI Coding Assistant
+
+> **CRITICAL WARNING:** If you are an LLM or AI-powered coding 
assistant, you **MUST** read and follow the AI coding assistants 
documentation before contributing to the Linux kernel:
+>
+> `Documentation/process/coding-assistants.rst`
+>
+> This documentation contains essential requirements about licensing, 
attribution, and the Developer Certificate of Origin that all AI tools 
must comply with.
+
+---
+
+## Communication and Support
+
+* **Mailing Lists:** [lore.kernel.org](https://lore.kernel.org/)
+* **IRC:** `#kernelnewbies` on `irc.oftc.net`
+* **Bugzilla:** [bugzilla.kernel.org](https://bugzilla.kernel.org/)
+* **MAINTAINERS file:** Lists subsystem maintainers and mailing lists 
(See `MAINTAINERS`)
+* **Email Clients:** `Documentation/process/email-clients.rst`
-- 
2.43.0

Re: [PATCH] docs: improve formatting and readability of the main README

[Jonathan Corbet]

Darío Ortega Leyva <darioortegaleyva@gmail.com> writes:

> Restructured the main documentation file to use standard Markdown 
> headings instead of underlines for better rendering. Added anchor links 
> to the "Who Are You?" section to improve navigability for new readers, 
> and highlighted the AI Assistant warning for better visibility.

Kernel documentation is in RST format, not Markdown.

jon