Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From rampstack-skills
Designs documentation systems: decides what gets documented, where, by whom, and how to keep docs fresh. Use for audits, tool selection, or fixing stale docs.
npx claudepluginhub rampstackco/claude-skills --plugin rampstack-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/rampstack-skills:documentation-strategyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Decide what gets documented, where, by whom, and how it stays fresh. Stack-agnostic. Applies to internal team docs, product docs, runbooks, READMEs, and knowledge bases.
Establish documentation standards that keep docs current, discoverable, and useful. Use when scaling team or improving knowledge retention.
Documentation levels and types (README, architecture, API, runbooks), keeping docs current and discoverable.
Guides project documentation structure, file organization, content requirements by project phase, and best practices for README.md, ARCHITECTURE.md, API docs, and more.
Share bugs, ideas, or general feedback.
Decide what gets documented, where, by whom, and how it stays fresh. Stack-agnostic. Applies to internal team docs, product docs, runbooks, READMEs, and knowledge bases.
team-onboarding-playbook)content-and-copy)content-strategy)code-review-web)content-and-copy)Different categories of doc serve different purposes. Conflating them is how docs get bad.
What things are. Looked up when needed.
Examples: API reference, configuration options, glossary, architecture diagrams, contact lists, decision log entries.
Properties:
How to do specific tasks. Procedural.
Examples: "Deploy to staging," "Reset a password," "Onboard a new contractor," "Run the backup restore drill."
Properties:
Why things are the way they are. Conceptual.
Examples: architecture rationale, design decision records (ADRs), strategy docs, vision documents.
Properties:
Learning-oriented. Walks someone from zero to capable.
Examples: "Getting started with our codebase," "Your first deploy," onboarding pathways.
Properties:
(This four-way split is the Diátaxis framework, well-known in tech writing. Memorize it.)
Different docs serve different audiences with different stakes.
Public docs, customer KBs, API references. High visibility, slow change.
Standards:
Docs used across teams: shared APIs, common services, company-wide processes.
Standards:
Docs for the team that owns them: how the team works, runbooks, decisions.
Standards:
Notes, drafts, work-in-progress. Not for others.
Standards:
Docs derived from code: API references generated from comments, schemas, etc.
Standards:
The tiering matters because the maintenance bar differs. Asking team-internal docs to meet customer-facing standards is wasteful and unsustainable.
The audit is often eye-opening. Most teams have more docs than they realize, in more places than they realize.
For each doc:
Some docs are mixed. Note the dominant category.
What documentation does the team need that doesn't exist?
Common gaps:
Ask people what they wish were documented. They know.
Docs that are:
Delete or archive. Stale docs are worse than missing docs (people might trust them).
Where docs live affects whether they're maintained.
Common locations:
Don't aim for one home. Aim for a clear answer to "where does this kind of doc live?"
Every doc has an owner. Without an owner, it goes stale.
Owner can be:
If an owner isn't obvious, the doc may not deserve to exist.
Per tier:
| Tier | Review cadence |
|---|---|
| Customer-facing | Per release, plus quarterly |
| Cross-team | Quarterly |
| Team-internal | Quarterly |
| Personal scratchpad | None |
| Auto-generated | On every change |
Maintenance includes:
Documentation isn't a separate project. It's part of the work that produces it.
The team that ships features without docs has less than they think they have.
Even great docs are useless if no one finds them.
What's measurable depends on the platform:
For internal docs, the qualitative measure is often more useful: are the same questions getting asked over and over? If yes, the docs aren't doing their job (either they don't exist, aren't found, or aren't clear).
Every code repo has a README that answers:
Five sentences each, often. Length isn't the goal. The READ-it-ME promise is.
Per significant decision:
# ADR-NNN: [Title]
Status: [Proposed / Accepted / Deprecated / Superseded]
Date: [Date]
## Context
[What's the situation? What forces are at play?]
## Decision
[What was decided?]
## Consequences
[What happens because of this decision? Both good and bad.]
ADRs accumulate. They become the explanation layer for "why are we doing it this way."
Per system:
See incident-response and backup-and-disaster-recovery for runbook standards.
Per role:
See team-onboarding-playbook.
Lightweight version of ADRs. Date, decision, decider, why. Keeps a record without ceremony.
Terms that have specific meaning in the team or product. Reduces confusion. Trains AI tools too (more on that later).
The tool is less important than the discipline. That said:
| Tool category | Examples | Best for |
|---|---|---|
| Wiki | Notion, Confluence, GitBook | Cross-team, internal |
| Markdown in code | GitHub, GitLab, Bitbucket | READMEs, ADRs, technical |
| Docs sites | Docusaurus, Mintlify, ReadMe | Customer-facing, public docs |
| Internal sites | MkDocs, custom | Team-specific patterns |
Considerations:
For small teams: a single wiki tool is plenty. For larger: tiered tools.
LLMs and AI assistants increasingly read documentation. Some considerations:
llms.txt if relevantDocumentation as a "later" task. Always written later. Later means never. Make docs part of the work.
One mega-doc for everything. Wiki page that's 8,000 words. No one reads it. Break by category and topic.
Stale docs that nobody trusts. "Probably out of date" is the thought that kills documentation. Either keep current or archive.
Docs everyone agrees should exist but no one writes. The team agrees onboarding docs would be valuable. Months pass. No one writes them. Make ownership specific.
Wikis that are graveyards. Lots of pages, no one trusts any of them. Audit, archive, restart with a slimmer set.
Docs separated from code. API docs in a wiki, code in a repo. They drift. Co-locate.
Docs without examples. Reference without examples is hard to use. Examples make it concrete.
Examples that don't run. Code examples that worked once, drifted. Test examples in CI where possible.
Long-form when reference would do. A 2,000-word doc explaining what a 30-row table would. Use the right form.
Multiple sources of truth. Same info in three places, all slightly different. Pick canonical, redirect others.
Doc tools no one uses. Adopted because of a feature; team doesn't actually use it. Pick tools the team will use.
Doc style guide that's longer than the docs. Process beats product. Guide should be short.
No way to mark docs as deprecated. Old docs sit alongside current ones with no indication. Add a "deprecated" or "archived" status.
No analytics. No idea what's being used or what's missing. Even basic page views inform priorities.
Docs that read like specifications. Dense, formal, hard to scan. Write for the reader.
A documentation strategy document includes:
references/doc-types-guide.md: Detailed guide to the four doc types (reference, how-to, explanation, tutorial) with examples and templates for each.