Improve Chapter 01 authoritative documentation lesson

docs/lessons/01_where_to_start/1.08_other_authoritative_documentation.md

@@ -1,74 +1,120 @@
 # 1.08 Other Authoritative Documentation
 
+Man pages tell you how a command behaves on the machine in front of you. Other authoritative documentation tells you what the project, distribution, vendor, or standards body intended, supports, and still recommends.
 
+For an operator, the skill is not "find a blog post." The skill is to rank sources, match them to the system you are touching, and keep enough notes that another admin can understand why you trusted a source.
 
 !!! abstract "What you will learn"
-    - Explain where **1.08 Other Authoritative Documentation** fits in day-to-day Linux operations.
-    - Use current Linux tooling to inspect, change, and verify the relevant system behavior.
-    - Connect the concept to a real operational scenario: a first-week junior admin onboarding into a small cloud team.
-
-!!! example "Field story"
-    Imagine a first-week junior admin onboarding into a small cloud team. Your job is not to memorize a command; it is to build a short evidence trail, choose a low-risk change, and prove whether the system improved.
+    - Identify which documentation source is authoritative for a Linux question.
+    - Prefer version-matched distribution, upstream, vendor, and standards documentation over generic web results.
+    - Record documentation evidence before making operational changes.
+    - Recognize when older guides, copied commands, or community answers need extra verification.
 
 !!! success "Operator principle"
-    Identify the OS, distribution, support window, and package source before changing anything.
-
-## Hands-on practice
+    Trust documentation closest to the component owner and closest to your installed version.
 
-Run these on a disposable VM, container, or lab machine unless the lesson explicitly says otherwise.
+## A Practical Trust Order
 
-1. Inspect the current state with a read-only command related to this topic.
-2. Save the command and output in a short lab note.
-3. Make one reversible change or simulate the change in a sandbox.
-4. Re-run the inspection and explain what changed.
+No single source is always best. Use the source that owns the decision you are trying to make.
 
-## Check your understanding
+1. **Local documentation and configuration**: `/usr/share/doc`, package changelogs, example configs, and files already deployed on the host show what this system actually has installed.
+2. **Distribution documentation**: Debian, Ubuntu, Fedora, Red Hat, Rocky Linux, AlmaLinux, Arch, SUSE, and FreeBSD documentation explain packaging, defaults, service names, filesystem paths, and support policy for their builds.
+3. **Upstream project documentation**: systemd, OpenSSH, Nginx, Apache, PostgreSQL, Kubernetes, Docker, and kernel documentation explain the component's design and current feature behavior.
+4. **Vendor or cloud provider documentation**: AWS, Azure, Google Cloud, hardware vendors, and appliance vendors explain platform-specific limits, images, networking, storage, and support contracts.
+5. **Standards and protocol references**: RFCs, POSIX, filesystem hierarchy references, and security benchmarks help when behavior must interoperate across systems.
+6. **Community sources**: forums, Q&A sites, blogs, and AI answers can be useful leads, but treat them as hints until confirmed against an authoritative source and a lab test.
 
-- What evidence would tell you that this system is healthy?
-- What is the riskiest command in this lesson, and how would you make it safer?
-- How would you explain section 1.8 to a teammate during an incident handoff?
+## Match the Source to the System
 
+Start by identifying the system and package involved:
 
-Learning to navigate Linux requires more than just hands-on experience. One of the essential skills you’ll need on your journey is the ability to find, understand, and make use of authoritative documentation. Here, in this section, we'll focus on introducing some of the key sources of authoritative documentation for Linux that will assist you in your learning.
+```bash
+cat /etc/os-release
+uname -a
+systemctl --version 2>/dev/null || true
+apt-cache policy openssh-server 2>/dev/null || true
+dnf info openssh-server 2>/dev/null || true
+```
 
-## Linux Documentation Project
+Those commands help answer practical questions:
 
-Let's start with the **Linux Documentation Project (LDP)**. This project is like the library of Alexandria for Linux, a rich trove of guides, tutorials, and detailed manpages. It provides information on everything from shell scripting basics to kernel compilation procedures.
+- Is this Ubuntu, Debian, Fedora, RHEL-family, SUSE, Arch, FreeBSD, or something else?
+- Is the package from the distribution, a vendor repository, source build, container image, or internal mirror?
+- Is the documentation you found written for the same major release?
+- Does the guide assume `systemd`, `OpenRC`, `rc.d`, containers, cloud-init, SELinux, AppArmor, or another platform detail?
 
-To access LDP, you just need to open your favorite web browser and type in 'www.tldp.org'. The website has a very intuitive interface, with different sections catering to beginners, intermediate, and advanced users.
+If the answer is unclear, stop and collect more evidence before changing the host.
 
-For instance, if you're just starting, you would likely find the 'Guides' section helpful as it contains a number of how-to documents tailored for beginners.
+## Useful Authoritative Sources
 
-## Linux Kernel Documentation
+Keep a short list of source families in your notes:
 
-The **Linux Kernel Documentation** is, as the name suggests, focused squarely on the kernel— the heart of Linux. As the kernel is a highly complex and critical part of any Linux system, this documentation is more advanced and technical. However, if you're pursuing a deeper understanding of Linux, this should be your go-to source.
+- **Distribution docs**: installation guides, release notes, security advisories, package policies, upgrade guides, and administration manuals.
+- **Project docs**: upstream manuals, reference pages, release notes, migration guides, issue trackers, and configuration examples.
+- **Kernel docs**: `docs.kernel.org` and packaged kernel documentation for driver, filesystem, networking, cgroup, namespace, and security-subsystem behavior.
+- **Package docs on the host**: `/usr/share/doc/<package>/`, `/usr/share/man/`, `/etc/<service>/`, and packaged examples.
+- **Cloud and hardware docs**: image notes, instance metadata references, storage limits, network behavior, backup guarantees, and support boundaries.
+- **Security docs**: vendor advisories, distribution CVE trackers, CIS guidance, NIST publications, and official hardening guides.
 
-You can access the kernel documentation at 'www.kernel.org/doc/html/latest/'. Remember, it's a fantastic resource, but also highly technical. Prepare yourself for some serious learning!
+For Linux kernel internals, prefer current kernel documentation over old how-to pages. For distribution defaults, prefer your distribution's docs even when upstream documentation says a different path or service name.
 
-## Official Distro Documentation
+## Build a Documentation Note
 
-Every Linux distribution provides its own **Official Documentation**, tailor-made for its specific system configurations. Whether you are using Ubuntu, Fedora, Debian, or any other distribution, you ought to be familiar with its official documentation. It proves extremely helpful when installing software, troubleshooting issues, or understanding the unique aspects of the distribution.
+Before you make a change based on documentation, capture a small note:
 
-Official distro documentation can be found on the respective websites of each Linux distribution. For example, if you're using Ubuntu, you can find official Ubuntu documentation at 'help.ubuntu.com'.
+```text
+Question:
+System evidence:
+Package/version:
+Authoritative source:
+Source version/date:
+Relevant command or setting:
+Risk:
+Rollback:
+Verification:
+```
 
-Remember, in the realm of Linux, documentation is your guidebook ⛰️📖. Whether you're a beginner grasping fundamental concepts, or an advanced user delving into the kernels, authoritative documentation will always guide your way. Don’t forget, even the most seasoned Linux users often return to these resources. They are not just references, but toolsets for growth, exploration, and continual learning.## Linux Documentation Project
+Example:
 
-Let's start with the **Linux Documentation Project (LDP)**. This project is like the library of Alexandria for Linux, a rich trove of guides, tutorials, and detailed manpages. It provides information on everything from shell scripting basics to kernel compilation procedures.
+```text
+Question: Should this Ubuntu 24.04 server use sshd_config.d snippets?
+System evidence: ID=ubuntu, VERSION_ID=24.04; OpenSSH package from Ubuntu repo
+Package/version: openssh-server 1:9.6p1-3ubuntu13
+Authoritative source: Ubuntu man page and packaged sshd_config example
+Source version/date: local package documentation on host
+Relevant command or setting: /etc/ssh/sshd_config.d/*.conf
+Risk: bad syntax can block new SSH logins
+Rollback: keep an existing root console and remove the snippet
+Verification: sshd -t; open a second SSH session before closing the first
+```
 
-To access LDP, you just need to open your favorite web browser and type in 'www.tldp.org'. The website has a very intuitive interface, with different sections catering to beginners, intermediate, and advanced users.
+## Watch for Stale or Unsafe Documentation
 
-For instance, if you're just starting, you would likely find the 'Guides' section helpful as it contains a number of how-to documents tailored for beginners.
+Be skeptical when documentation:
 
-## Linux Kernel Documentation
+- Targets a different distribution or major version.
+- Uses commands that overwrite files with `>`, remove paths with `rm -rf`, or pipe remote scripts into a shell.
+- Disables SELinux, AppArmor, firewalls, TLS checks, or package signature checks without a narrow reason.
+- Says to "just reboot" without explaining what will change.
+- Solves an old init-system, networking, or package-manager problem that your system no longer has.
+- Has no publication date, no version, or no owner.
 
-The **Linux Kernel Documentation** is, as the name suggests, focused squarely on the kernel— the heart of Linux. As the kernel is a highly complex and critical part of any Linux system, this documentation is more advanced and technical. However, if you're pursuing a deeper understanding of Linux, this should be your go-to source.
+If a command is useful but risky, translate it into read-only inspection first. For example, read a file with `sed -n` or validate syntax with a dry-run command before editing.
 
-You can access the kernel documentation at 'www.kernel.org/doc/html/latest/'. Remember, it's a fantastic resource, but also highly technical. Prepare yourself for some serious learning!
+## Hands-on Practice
 
-## Official Distro Documentation
+Use a disposable VM, container, or lab host.
 
-Every Linux distribution provides its own **Official Documentation**, tailor-made for its specific system configurations. Whether you are using Ubuntu, Fedora, Debian, or any other distribution, you ought to be familiar with its official documentation. It proves extremely helpful when installing software, troubleshooting issues, or understanding the unique aspects of the distribution.
+1. Pick one installed service, such as OpenSSH, Nginx, Apache, cron, or systemd timers.
+2. Identify the OS and package version.
+3. Find one local source, one distribution source, and one upstream source for the same setting.
+4. Note one difference between the sources, such as path names, service names, defaults, or supported versions.
+5. Choose which source you would trust for a production change and explain why.
+6. Run one read-only command that verifies the setting on the local host.
 
-Official distro documentation can be found on the respective websites of each Linux distribution. For example, if you're using Ubuntu, you can find official Ubuntu documentation at 'help.ubuntu.com'.
+## Check Your Understanding
 
-Remember, in the realm of Linux, documentation is your guidebook ⛰️📖. Whether you're a beginner grasping fundamental concepts, or an advanced user delving into the kernels, authoritative documentation will always guide your way. Don’t forget, even the most seasoned Linux users often return to these resources. They are not just references, but toolsets for growth, exploration, and continual learning.
+- Why is upstream documentation not always the best source for distribution-specific service paths?
+- What evidence tells you that a guide matches your installed system?
+- When is a community answer useful, and what must you do before trusting it?
+- What should be included in a documentation note before a risky change?