From 625c8c8c95817f4afb7e83bc7ad1212b0f7a3a5a Mon Sep 17 00:00:00 2001 From: Josh Schmelzle Date: Tue, 29 Sep 2026 11:15:03 -0400 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20add=20Di=C3=A1taxis=20documentation?= =?UTF-8?q?=20types=20to=20README=20standards?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- style/README_STANDARDS.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/style/README_STANDARDS.md b/style/README_STANDARDS.md index 2952222..a4d8dca 100644 --- a/style/README_STANDARDS.md +++ b/style/README_STANDARDS.md @@ -26,7 +26,30 @@ Sections should appear in this order where applicable: 11. Authors 12. License -Deep debugging notes, workarounds, and edge-case instructions belong in a separate `TROUBLESHOOTING.md`, not the main README. +Deep debugging notes, workarounds, and edge-case instructions belong in a separate `TROUBLESHOOTING.md` (a how-to page), not the main README. + +## Documentation Types + +Classify every page by the reader's need, following [Diátaxis](https://diataxis.fr/). A page serves one need. Content for another need goes on its own page, linked. + +| Type | Reader need | Page content | Example | +|------|-------------|--------------|---------| +| Tutorial | Learn | One guided, end-to-end path that works for a newcomer | Build your first package | +| How-to | Get a task done | Imperative steps; assumes basic competence | Configure a reverse proxy | +| Reference | Look up a fact | Complete, accurate facts: options, defaults, endpoints, config keys. No steps, no rationale | CLI flags | +| Explanation | Understand why | Context, design rationale, trade-offs. No steps | Why services run under systemd | + +A README is the entry point: What / Why, short install and usage, links. When a repo's docs outgrow it, add a `docs/` folder with only the subfolders that have pages: + +```text +docs/ + tutorials/ + how-to/ + reference/ + explanation/ +``` + +Fix a page's type when you touch it for another reason. Do not rewrite docs in bulk. ## Headings From 96eb462282705fb3f6bd7de096c4910486369207 Mon Sep 17 00:00:00 2001 From: Josh Schmelzle Date: Tue, 29 Sep 2026 11:18:01 -0400 Subject: [PATCH 2/2] docs: place working notes and troubleshooting in the docs layout --- REPOS.md | 4 ++++ style/README_STANDARDS.md | 4 +++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/REPOS.md b/REPOS.md index 76722a9..734b2d0 100644 --- a/REPOS.md +++ b/REPOS.md @@ -86,5 +86,9 @@ issues are tracked against each repository. `wlanpi-fpms`, `wlanpi-hwtest`, `wlanpi-profiler`, and `wlanpi-webui` have any. - README link back to this repo: only `wlanpi-common` and `wlanpi-desktop`. +- `docs/` layout ([Documentation Types](style/README_STANDARDS.md#documentation-types)): + no repo uses the four type folders yet. `wlanpi-app`, `wlanpi-core`, + `wlanpi-mcp`, `wlanpi-misc-firmware`, `wlanpi-profiler`, and + `pi-gen-bookworm` have flat or ad-hoc `docs/` folders. - BSD-3-Clause migration: `wlanpi-bridge`, `wlanpi-chat-bot` (archived), `wlanpi-kernel`, `wlanpi-misc-packages`, and `wlanpi-wconsole` are MIT. diff --git a/style/README_STANDARDS.md b/style/README_STANDARDS.md index a4d8dca..c347eeb 100644 --- a/style/README_STANDARDS.md +++ b/style/README_STANDARDS.md @@ -26,7 +26,7 @@ Sections should appear in this order where applicable: 11. Authors 12. License -Deep debugging notes, workarounds, and edge-case instructions belong in a separate `TROUBLESHOOTING.md` (a how-to page), not the main README. +Deep debugging notes, workarounds, and edge-case instructions belong in a how-to page, not the main README: `TROUBLESHOOTING.md`, or `docs/how-to/troubleshooting.md` once the repo has a `docs/` folder. ## Documentation Types @@ -49,6 +49,8 @@ docs/ explanation/ ``` +Plans, PRDs, specs, and handover notes are working documents, not reader docs. Keep them outside the four type folders (for example `docs/plans/`). + Fix a page's type when you touch it for another reason. Do not rewrite docs in bulk. ## Headings