Skip to content

docs: add Diátaxis documentation types to README standards - #39

Merged
joshschmelzle merged 2 commits into
mainfrom
docs/diataxis-doc-types
Sep 29, 2026
Merged

joshschmelzle merged 2 commits into
mainfrom
docs/diataxis-doc-types

Conversation

@joshschmelzle

Copy link
Copy Markdown
Member

Problem

The README standards cover README structure only. There is no rule for pages beyond the README, so repos that outgrow it end up with flat docs/ folders that mix user guides, API facts, design notes, and working plans (wlanpi-core, wlanpi-mcp, wlanpi-profiler, and others).

Change

Adds a Documentation Types section to style/README_STANDARDS.md based on Diátaxis:

  • Each page serves one reader need: tutorial, how-to, reference, or explanation. Content for another need goes on its own linked page.
  • The README stays the entry point. Once docs outgrow it, use docs/{tutorials,how-to,reference,explanation}/, creating only the folders that have pages.
  • Plans, PRDs, specs, and handover notes stay outside the four type folders.
  • Troubleshooting is a how-to page.
  • Pages are fixed when touched for another reason, not rewritten in bulk.

REPOS.md records that no repo uses the layout yet and lists the six with ad-hoc docs/ folders.

No existing repo has to change now.

Validation

  • shellcheck install.sh: pass
  • actionlint: pass

@joshschmelzle joshschmelzle self-assigned this Sep 29, 2026
@joshschmelzle
joshschmelzle merged commit 6555955 into main Sep 29, 2026
1 check passed
@joshschmelzle
joshschmelzle deleted the docs/diataxis-doc-types branch September 29, 2026 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant