documentation_structure v1.0.0

name: "documentation_structure" description: "Organize a project's whole documentation set: information architecture, README vs docs/ split, navigation depth, versioning strategy, and anti-rot ownership practices. Triggers on 'structure our docs', 'docs are a mess', doc IA, doc versioning, or docs going stale." metadata: { "includeInPrompt": true }

Purpose

This skill is about the STRUCTURE of a documentation set, not how to write a page. It answers: what docs exist, what belongs in each, how they link and version, and how the set stays fresh over time. Writing craft (prose habits, README templates, runbook content) belongs to the documentation-habits skill.

Workflow

1. Audit. Inventory what exists: every markdown page, its audience, and its last real update. Then map what readers actually need against what exists. Group by reader journey (first-time setup, daily use, troubleshooting, contributing), not alphabetically. Mark gaps, overlaps, and pages that describe behavior that no longer exists.
2. Define the IA. Set 4 to 6 top-level sections max, each mapped to one reader journey. Write the tree two levels deep before adding a third; depth beyond 3 means a page should be split or a section renamed. Give every page a slug-style filename that survives renames (getting-started.md, not welcome-to-our-amazing-tool.md) and keep URLs stable even when titles change.
3. Split README vs docs/. The README is the doorway: what the project is, who it is for, a 60-second quickstart, and pointers into docs/. It holds nothing longer than a screenful per section. Everything reference-grade (API details, config tables, internals) lives in docs/ and is linked from the README, never duplicated there. If a fact appears in both places it will drift; one canonical home only.
4. Plan versioning. Pick one strategy and document the choice: latest-only (docs always describe the current release, old versions go to git history), branch-per-release (docs travel with release branches), or versioned subtrees (docs/v1/, docs/v2/). Latest-only is the default for fast-moving projects. Mark deprecated pages with a visible banner naming the replacement and a removal date; move removed pages to an archive/ folder instead of deleting them, so old links still resolve.
5. Set up anti-rot. Every page gets an owner and a last-verified date in its frontmatter. Adopt the PR rule: any PR that changes behavior must touch the docs for that behavior, or explain why not. Run a freshness check monthly and a broken-link check on the same cadence.
6. Include a freshness-check snippet the project can run from the repo root (git-backed docs):

bash
# Lists every docs/ page with its last git commit date, oldest first.
for f in $(find docs -name '*.md'); do
  echo "$(git log -1 --format='%ad' --date=short -- "$f") $f"
done | sort

Pages older than 6 months that describe active behavior go to the top of the review queue. For docs not in git, use file mtime instead (find docs -name '*.md' -printf '%T+ %p\n' | sort) and treat anything older than the same threshold the same way.

Output Contract

• A proposed tree: top-level sections with the one reader journey each serves, and the two-to-three page slots under each.
• A README-vs-docs/ boundary statement: what stays in the README and what moves out.
• A versioning decision: which strategy, where archived pages live, and how deprecation banners look.
• An anti-rot checklist: owner per page, last-verified convention, PR-doc rule wording, freshness-check cadence, broken-link cadence.
• A changelog slot: note where the changelog lives in the tree. Format discipline is owned by the changelog-discipline skill; this skill only names the slot.

Operating Rules

1. Journey-first. Organize around what the reader is trying to do. Task-based sections (setup, use, fix, build) beat topic-based sections most projects outgrow.
2. One canonical home per fact. Duplication between README and docs/ is the fastest path to rot. Link, do not copy.
3. Keep the tree shallow. Prefer renaming sections over nesting deeper. If a section needs more than 6 pages, it is probably two sections.
4. Stable slugs. Filenames and URLs do not change when titles do. Redirects or archive pages protect old links; renaming a file silently breaks bookmarks.
5. Version the decision, not just the docs. Record why the versioning strategy was chosen so a future maintainer does not silently invert it.
6. Anti-rot is a schedule, not a one-time pass. Freshness checks and link checks run on a calendar, and the PR-doc rule is enforced in review. A doc set with no maintenance cadence will rot regardless of how well it was structured on day one.