Skip to content
Skills Library
Programming · Planning

docs-architecture

/docs-architecture

Structure and write project documentation beyond the README. Use when docs have sprawled into an unnavigable pile, when users keep asking questions the docs already answer, when choosing a docs site generator (Docusaurus, MkDocs, VitePress, mdBook, Sphinx), or when planning a docs information architecture. Covers the Diataxis framework (tutorial/how-to/reference/explanation), versioning docs across releases, API reference generation, doc testing, and migration guides. Also use for "write docs for this project" or "our docs are bad".

Repository
oss-skills ↗
Licence
Apache-2.0
Last repository change
08.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.08.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Structure and write project documentation beyond the README. Use when docs have sprawled into an unnavigable pile, when users keep asking questions the docs already answer, when choosing a docs site generator (Docusaurus, MkDocs, VitePress, mdBook, Sphinx), or when planning a docs information architecture. Covers the Diataxis framework (tutorial/how-to/reference/explanation), versioning docs across releases, API reference generation, doc testing, and migration guides. Also use for "write docs for this project" or "our docs are bad".

Triggers from the description

write docs for this projectour docs are bad
Original author description

Structure and write project documentation beyond the README. Use when docs have sprawled into an unnavigable pile, when users keep asking questions the docs already answer, when choosing a docs site generator (Docusaurus, MkDocs, VitePress, mdBook, Sphinx), or when planning a docs information architecture. Covers the Diataxis framework (tutorial/how-to/reference/explanation), versioning docs across releases, API reference generation, doc testing, and migration guides. Also use for "write docs for this project" or "our docs are bad".

How it works

  1. Diátaxis: the four modes
  2. Let the issue tracker write your docs
  3. Choosing a generator
  4. Reference docs must be generated
  5. Docs must be tested
  6. Versioning
  7. Migration guides
  8. Writing rules that survive translation
  9. Anti-patterns
Original SKILL.md headings · 155 lines, 1,134 words
SKILL.md preview
---
name: docs-architecture
description: Structure and write project documentation beyond the README. Use when docs have sprawled into an unnavigable pile, when users keep asking questions the docs already answer, when choosing a docs site generator (Docusaurus, MkDocs, VitePress, mdBook, Sphinx), or when planning a docs information architecture. Covers the Diataxis framework (tutorial/how-to/reference/explanation), versioning docs across releases, API reference generation, doc testing, and migration guides. Also use for "write docs for this project" or "our docs are bad".
---

# Documentation Architecture

Most bad documentation is not badly written — it is badly *sorted*. A tutorial with
reference material interleaved fails at both jobs. Fix the structure first; the prose
problem usually dissolves.

## Diátaxis: the four modes

Every documentation page serves exactly one of four purposes. Mixing them is the root
cause of most docs complaints.

| | **Learning** (study) | **Working** (doing) |
|---|---|---|
| **Practical steps** | **Tutorial** — a guided first success | **How-to** — a recipe for a specific goal |
| **Theoretical knowledge** | **Explanation** — why it works this way | **Reference** — exhaustive, dry, accurate |

- **Tutorial** — "Build your first X in 10 minutes." One path, no choices, guaranteed
  to work. The reader is a beginner; every decision you offer them is a chance to
  fail. Optimize for *finishing*, not for teaching everything.
- **How-to** — "How to deploy behind a proxy." Assumes competence. Starts at a goal,
  ends at the goal. Titled `How to <verb> <object>` so search finds it.
- **Reference** — the API, the CLI flags, the config schema. Complete, consistent,
  boring. Generated from source wherever possible. No teaching, no opinions.
- **Explanation** — "Why we use content-addressed storage." Read in an armchair, not
  at a keyboard. This is where design rationale, tradeoffs, and history belong.

Diagnostic: pick any page and name its quadrant. If you cannot, that page is the
problem. Common failure — a "Getting Started" page that is 30% tutorial, 50% reference
and 20% explanation, so a beginner drowns and an expert cannot find the flag list.

Minimum viable docs, in order of when to add them:

1. README (see `readme-that-converts`)
2. One tutorial — the 10-minute first success
3. Reference — generated
4. How-tos — one per recurring support question, written *when* it recurs
5. Explanations — when "why is it like this?" gets asked twice

## Let the issue tracker write your docs

The highest-leverage docs process there is: every question answered more than once
becomes a how-to page.

```bash
gh issue list --state all --limit 200 --json title,labels,comments \
  --jq '.[] | select(.labels[]?.name == "question") | .title'
```

Cluster the results. Each cluster of three or more is a missing page. Then close
future duplicates with a link — and if you find yourself linking the same page while
also explaining it, the page is not doing its job yet.

## Choosing a generator

| Tool | Best for | Cost |
|---|---|---|
| **MkDocs + Material** | Python projects, fast start, excellent defaults | Python toolchain |
| **Docusaurus** | JS/TS ecosystems, versioned docs, i18n, React embeds | Node build, heavier |
| **VitePress** | Lightweight, fast builds, Vue-adjacent | Fewer batteries |
| **mdBook** | Rust projects, books, minimal deps | Limited plugins |
| **Sphinx** | Scientific Python, deep autodoc, cross-refs | Steepest learning curve |
| **Just `docs/*.md`** | Under ~10 pages | No search, no versioning |

Do not build a docs site before you have ~10 pages. Markdown in `docs/` renders fine
on GitHub and costs nothing to maintain. The site is a response to scale, not a
prerequisite for it.

Whatever you pick: **deploy on merge to main**, from CI, to GitHub Pages or similar.
Docs that require a human to publish are docs that go stale.

## Reference docs must be generated

Hand-written API reference drifts within weeks. Generate from the source of truth:

```bash
typedoc --out docs/api src/index.ts       # TypeScript
sphinx-apidoc -o docs/api src/            # Python (or mkdocstrings)
cargo doc --no-deps                        # Rust
godoc / pkg.go.dev                         # Go (automatic)
```

Then **fail CI when public symbols lack docstrings**. That single gate does more for
reference quality than any style guide.

## Docs must be tested

Documentation is code that runs in your users' terminals. Broken examples destroy
trust faster than missing examples.

```bash
pytest --doctest-modules            # Python doctests
cargo test --doc                    # Rust doc tests
mdbook test                         # mdBook code blocks
npx markdown-link-check docs/**/*.md   # dead links
lychee --no-progress .               # faster link checker, handles anchors
```

For untestable-by-default markdown, extract code fences in CI and execute them against
a fresh install. If a snippet cannot be run automatically, mark it `text` rather than
a language, so nobody thinks it was verified.

## Versioning

Once users are on more than one major version, docs must be versioned — a v3 doc page
answering a v2 user's search is an active harm.

- **Version at major releases only.** Per-patch versions produce dozens of dead trees.
- **Keep the current version at the canonical URL**; archive old ones under `/v2/`.
- **Banner every archived page**: "You are viewing docs for v2. [Latest is v4.]"
- **Set `rel=canonical`** to the current version so search engines stop surfacing the
  old page above the new one. This is the single most common docs-SEO failure.
- **Delete docs for unsupported versions** rather than leaving them unmarked.

## Migration guides

For every breaking change, a migration guide. This is the difference between users
upgrading and users staying on an old version forever (and then filing bugs about it).

Structure that works:

1. **Why** the change happened — one paragraph, no apologies needed
2. **What breaks** — an exhaustive list, most-common first
3. **Before/after code** for each break
4. **Automated path** — a codemod, `sed` line, or `--fix` flag where possible
5. **Escape hatch** — how to stay on the old behavior, and until when

Ship the guide *with* the release, not after. See `release-engineering`.

## Writing rules that survive translation

- **Second person, imperative.** "Run `x`", not "the user should run `x`."
- **Present tense.** "Returns a Promise", not "will return".
- **One idea per paragraph.** Three sentences maximum.
- **Front-load the answer.** Do not build to a conclusion; state it and then explain.
- **Concrete over abstract.** "10,000 rows" not "large datasets".
- **No `simply`, `just`, `obviously`, `easily`.** When a reader is stuck, these words
  tell them the problem is their intelligence.
- **Define jargon on first use**, or link it. Your users are not all native speakers.
- **Every code block is copy-pasteable** and names its language for highlighting.
- **Alt text on every image.** It is accessibility and it is SEO.

## Anti-patterns

- **Docs in the wiki.** Not versioned, not reviewed, not in the PR diff, ungrepable.
  Move to `docs/` in-repo.
- **A "Getting Started" that is actually reference.**
- **Reference written by hand.**
- **Examples that don't run.**
- **No search.** Past ~20 pages, search *is* the navigation.
- **Docs that require the site to build to be read.** Keep source markdown readable
  on GitHub; avoid generator-specific syntax in every paragraph.
- **A docs rewrite instead of a docs restructure.** Re-sorting existing pages into
  Diátaxis quadrants usually recovers 80% of the value for 20% of the work.

Versions

The database has no other skills named docs-architecture.

Database snapshot: 13.11.2026 · package version 07aec64dc67d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95Diataxis-Documentation
    Diataxis-based documentation methodology for creating, organizing, and planning documentation. USE WHEN user says 'set up docs', 'create documentation', 'document this project', 'plan documentation', 'organize docs', 'restructure docs', 'getting started guide', 'write a…
  • 90doc-writer-doc-site
    Authors documentation-site pages and designs information architecture — navigation, sidebar taxonomy, page hierarchy, cross-linking strategy, doc-site generator conventions (Docusaurus, MkDocs, Nextra, VitePress, etc.). Pulled by the `doc-writer` specialist. TRIGGER: \"build out…
  • 100scientific-documentation
    Use when the user asks about setting up docs for a Python package, configuring Sphinx or MkDocs, writing NumPy-style docstrings, or deploying to Read the Docs. Set up and maintain documentation for scientific Python packages. Covers Sphinx, MkDocs, NumPy-style docstrings,…
  • 100technical-writing
    Technical Writing Specialist - Clear, comprehensive technical documentation. [VAD] README files, API documentation, tutorials, user guides, architecture docs. OpenAPI/Swagger specifications, Markdown, Docusaurus, MkDocs. [NÄR] Use when: README, documentation, API docs, tutorial,…
  • 96docusaurus-docs-site
    Use when turning repo docs into a Docusaurus site.
  • 100documentation
    This skill should be used when the user is setting up MkDocs Material, configuring mkdocstrings, writing docstrings, generating API reference pages, structuring documentation with the Diataxis framework, deploying docs to GitHub Pages or ReadTheDocs, or writing a README. Covers…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.