Design and run a documentation system for a team or product

Documentation strategy

by rampstackco · MIT license · ★ 901 on GitHub · updated Sep 15

Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping…

---
name: documentation-strategy
description: "Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding takes too long."
category: process-and-team
catalog_summary: "Documentation systems, what to document, maintenance cadence"
display_order: 2
---

# Documentation Strategy

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.

---

## When to use

- Setting up documentation for a new team or product
- Auditing existing documentation

Overview

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.

What you get

Auditwhat exists, where, in what state
Tiering and categorizationthe framework applied to existing docs
Gap listwhat should exist but doesn't
Tool decisionswhere each kind of doc lives
Ownership mapwho owns what
Maintenance cadencewhat's reviewed when

Manual install (npx, ZIP)

Claude Codenpx skills add rampstackco/claude-skills --skill documentation-strategy -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/rampstackco/claude-skills/tar.gz/3d4510a94a76 \
  | tar -xz -C ~/.claude/skills --strip-components=2 claude-skills-3d4510a94a76/skills/documentation-strategy

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/4c4a490a437c68aec6a2/documentation-strategy.zip" -OutFile "$env:TEMP\documentation-strategy.zip"; Expand-Archive "$env:TEMP\documentation-strategy.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md12.8 KB
references/1 file · 10.3 KB

Read the files here

rampstackco/3d4510a2 files

SKILL.md12.8 KB

SKILL.md

Show the full text429 lines

documentation-strategy/SKILL.md429 lines · 12.8 KB

PreviewCode

Outline

RawView on GitHub

Documentation Strategy

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.

When to use

Setting up documentation for a new team or product
Auditing existing documentation
Fixing stale or scattered docs
Choosing a documentation tool or platform
Defining what gets documented and what doesn't
Establishing maintenance cadence
Scoping technical writing work
Designing onboarding documentation (use alongside team-onboarding-playbook)

When NOT to use

Writing the actual content of a single document (use content-and-copy)
Customer-facing knowledge base copy (use content-strategy)
Code comments and inline documentation (covered by code-review-web)
One-off blog posts or articles (use content-and-copy)

Required inputs

The audience (internal, external, customer, dev, exec)
Existing docs and their state (where, what shape, last updated)
Team size and growth trajectory
The kinds of work that produce documentation (engineering, product, ops, support)
Tools currently in use

The framework: 4 categories of documentation

Different categories of doc serve different purposes. Conflating them is how docs get bad.

Category 1: Reference

What things are. Looked up when needed.

Examples: API reference, configuration options, glossary, architecture diagrams, contact lists, decision log entries.

Properties:

Comprehensive
Fact-checked, kept accurate
Searchable
Stable structure (links don't break)
Version-aware where relevant

Category 2: How-to

How to do specific tasks. Procedural.

Examples: "Deploy to staging," "Reset a password," "Onboard a new contractor," "Run the backup restore drill."

Properties:

Step-by-step
Tested by someone who didn't write it
Includes the prerequisites
Includes troubleshooting
Versioned to the system it documents

Category 3: Explanation

Why things are the way they are. Conceptual.

Examples: architecture rationale, design decision records (ADRs), strategy docs, vision documents.

Properties:

Narrative
Captures context (the why)
Often historical (why we built it this way)
Links to evidence

Category 4: Tutorial

Learning-oriented. Walks someone from zero to capable.

Examples: "Getting started with our codebase," "Your first deploy," onboarding pathways.

Properties:

Sequenced from simple to complex
Hands-on
Doesn't assume prior knowledge in scope
Has clear completion criteria

(This four-way split is the Diátaxis framework, well-known in tech writing. Memorize it.)

The framework: 5 tiers of doc

Different docs serve different audiences with different stakes.

Tier 1: Customer-facing

Public docs, customer KBs, API references. High visibility, slow change.

Standards:

Editorial review
Version control
Clear ownership
High freshness bar
Tied to release

Tier 2: Cross-team / shared

Docs used across teams: shared APIs, common services, company-wide processes.

Standards:

Cross-team ownership clear
Update obligations on changes
Mid-to-high freshness bar

Tier 3: Team-internal

Docs for the team that owns them: how the team works, runbooks, decisions.

Standards:

Team-owned, team-maintained
Mid freshness bar
Useful for the next person joining

Tier 4: Personal scratchpad

Notes, drafts, work-in-progress. Not for others.

Standards:

Low maintenance
Don't link from official docs
Promote to higher tier when valuable

Tier 5: Auto-generated

Docs derived from code: API references generated from comments, schemas, etc.

Standards:

Generation is automated, runs in CI
Single source of truth (the code)
Reviewed for usability, not freshness (that's automatic)

The tiering matters because the maintenance bar differs. Asking team-internal docs to meet customer-facing standards is wasteful and unsustainable.

Workflow

Step 1: Audit current state

What docs exist?
Where do they live? (often: scattered)
Who owns each?
How fresh are they?
Are they actually used? (check page views or referrals if measurable)

The audit is often eye-opening. Most teams have more docs than they realize, in more places than they realize.

Step 2: Categorize and tier

For each doc:

Category (reference / how-to / explanation / tutorial)
Tier (customer / shared / team / scratchpad / generated)

Some docs are mixed. Note the dominant category.

Step 3: Identify gaps

What documentation does the team need that doesn't exist?

Common gaps:

"How does X actually work?" no answer
Onboarding for the role no one's onboarded recently
Runbook for a system that's never broken (yet)
Decision rationale for "why are we doing it this way"

Ask people what they wish were documented. They know.

Step 4: Identify dead weight

Docs that are:

Out of date and not getting updated
Duplicated across places (one is canonical, others should redirect or be deleted)
About things that no longer exist
Drafts abandoned long ago

Delete or archive. Stale docs are worse than missing docs (people might trust them).

Step 5: Pick the home(s)

Where docs live affects whether they're maintained.

Common locations:

Code repo (markdown): for docs tightly coupled to code (READMEs, ADRs, runbooks for the service)
Wiki / Notion / Confluence: for cross-team and team-internal
Docs site (Docusaurus, Mintlify, custom): for customer-facing
Tickets / decision logs: for ephemeral records

Don't aim for one home. Aim for a clear answer to "where does this kind of doc live?"

Step 6: Establish ownership

Every doc has an owner. Without an owner, it goes stale.

Owner can be:

A team
A role (the on-call rotation, the PM, the EM)
A person, with a backup

If an owner isn't obvious, the doc may not deserve to exist.

Step 7: Establish maintenance cadence

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:

Verify accuracy
Update for changed systems
Archive what's no longer relevant
Address user feedback

Step 8: Make doc updates part of work

Documentation isn't a separate project. It's part of the work that produces it.

New feature: docs are part of the feature
New process: doc is part of the rollout
Decision made: ADR or decision-log entry filed
Bug postmortem: runbook updated
New hire: onboarding doc updated based on their experience

The team that ships features without docs has less than they think they have.

Step 9: Make docs discoverable

Even great docs are useless if no one finds them.

Search that actually works (most platforms; some better than others)
Index pages for major topics
Cross-links between related docs
Search aliases for common alternative phrasings
Pinning the most-used docs

Step 10: Measure

What's measurable depends on the platform:

Page views
Search queries (and zero-result queries)
"Was this helpful?" feedback
Time on page
Referral patterns

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).

Specific patterns

README per project

Every code repo has a README that answers:

What is this?
How do I run it?
How do I contribute?
Where do I find more info?

Five sentences each, often. Length isn't the goal. The READ-it-ME promise is.

ADR (Architecture Decision Record)

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."

Runbook

Per system:

What it is
How to access it
Common operations (with commands)
Common failure modes
Restore from backup procedure
Escalation contacts

See incident-response and backup-and-disaster-recovery for runbook standards.

Onboarding pathway

Per role:

Day 1
Week 1
Month 1
90 days

See team-onboarding-playbook.

Decision log

Lightweight version of ADRs. Date, decision, decider, why. Keeps a record without ceremony.

Glossary

Terms that have specific meaning in the team or product. Reduces confusion. Trains AI tools too (more on that later).

Tooling

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:

Search quality (a poor search makes everything worse)
Editor quality (people won't write in painful editors)
Version control (can you see history?)
Permissions (right people can read and write)
API and integration (for automation)
Cost at your scale

For small teams: a single wiki tool is plenty. For larger: tiered tools.

LLMs and AI assistants increasingly read documentation. Some considerations:

Clear, consistent structure helps both humans and AI
A glossary of terms helps both
File-level metadata (front matter) helps tools
Public docs may be read by AI crawlers; consider an llms.txt if relevant
AI-generated drafts are a starting point, not a final answer; humans review

Failure patterns

Documentation 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.

Output format

A documentation strategy document includes:

Audit: what exists, where, in what state
Tiering and categorization: the framework applied to existing docs
Gap list: what should exist but doesn't
Tool decisions: where each kind of doc lives
Ownership map: who owns what
Maintenance cadence: what's reviewed when
Style guide (brief): consistency standards
Roadmap: prioritized work to fill gaps and close out dead weight

Reference files

references/doc-types-guide.md: Detailed guide to the four doc types (reference, how-to, explanation, tutorial) with examples and templates for each.

1	---
2	name: documentation-strategy
3	description: "Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding takes too long."
4	category: process-and-team
5	catalog_summary: "Documentation systems, what to document, maintenance cadence"
6	display_order: 2
7	---
8
9	# Documentation Strategy
10
11	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.
12
13	---
14
15	## When to use
16
17	- Setting up documentation for a new team or product
18	- Auditing existing documentation
19	- Fixing stale or scattered docs
20	- Choosing a documentation tool or platform
21	- Defining what gets documented and what doesn't
22	- Establishing maintenance cadence
23	- Scoping technical writing work
24	- Designing onboarding documentation (use alongside `team-onboarding-playbook`)
25
26	## When NOT to use
27
28	- Writing the actual content of a single document (use `content-and-copy`)
29	- Customer-facing knowledge base copy (use `content-strategy`)
30	- Code comments and inline documentation (covered by `code-review-web`)
31	- One-off blog posts or articles (use `content-and-copy`)
32
33	---
34
35	## Required inputs
36
37	- The audience (internal, external, customer, dev, exec)
38	- Existing docs and their state (where, what shape, last updated)
39	- Team size and growth trajectory
40	- The kinds of work that produce documentation (engineering, product, ops, support)
41	- Tools currently in use
42
43	---
44
45	## The framework: 4 categories of documentation
46
47	Different categories of doc serve different purposes. Conflating them is how docs get bad.
48
49	### Category 1: Reference
50
51	What things are. Looked up when needed.
52
53	Examples: API reference, configuration options, glossary, architecture diagrams, contact lists, decision log entries.
54
55	Properties:
56	- Comprehensive
57	- Fact-checked, kept accurate
58	- Searchable
59	- Stable structure (links don't break)
60	- Version-aware where relevant
61
62	### Category 2: How-to
63
64	How to do specific tasks. Procedural.
65
66	Examples: "Deploy to staging," "Reset a password," "Onboard a new contractor," "Run the backup restore drill."
67
68	Properties:
69	- Step-by-step
70	- Tested by someone who didn't write it
71	- Includes the prerequisites
72	- Includes troubleshooting
73	- Versioned to the system it documents
74
75	### Category 3: Explanation
76
77	Why things are the way they are. Conceptual.
78
79	Examples: architecture rationale, design decision records (ADRs), strategy docs, vision documents.
80
81	Properties:
82	- Narrative
83	- Captures context (the why)
84	- Often historical (why we built it this way)
85	- Links to evidence
86
87	### Category 4: Tutorial
88
89	Learning-oriented. Walks someone from zero to capable.
90
91	Examples: "Getting started with our codebase," "Your first deploy," onboarding pathways.
92
93	Properties:
94	- Sequenced from simple to complex
95	- Hands-on
96	- Doesn't assume prior knowledge in scope
97	- Has clear completion criteria
98
99	(This four-way split is the Diátaxis framework, well-known in tech writing. Memorize it.)
100
101	---
102
103	## The framework: 5 tiers of doc
104
105	Different docs serve different audiences with different stakes.
106
107	### Tier 1: Customer-facing
108
109	Public docs, customer KBs, API references. High visibility, slow change.
110
111	Standards:
112	- Editorial review
113	- Version control
114	- Clear ownership
115	- High freshness bar
116	- Tied to release
117
118	### Tier 2: Cross-team / shared
119
120	Docs used across teams: shared APIs, common services, company-wide processes.
121
122	Standards:
123	- Cross-team ownership clear
124	- Update obligations on changes
125	- Mid-to-high freshness bar
126
127	### Tier 3: Team-internal
128
129	Docs for the team that owns them: how the team works, runbooks, decisions.
130
131	Standards:
132	- Team-owned, team-maintained
133	- Mid freshness bar
134	- Useful for the next person joining
135
136	### Tier 4: Personal scratchpad
137
138	Notes, drafts, work-in-progress. Not for others.
139
140	Standards:
141	- Low maintenance
142	- Don't link from official docs
143	- Promote to higher tier when valuable
144
145	### Tier 5: Auto-generated
146
147	Docs derived from code: API references generated from comments, schemas, etc.
148
149	Standards:
150	- Generation is automated, runs in CI
151	- Single source of truth (the code)
152	- Reviewed for usability, not freshness (that's automatic)
153
154	The tiering matters because the maintenance bar differs. Asking team-internal docs to meet customer-facing standards is wasteful and unsustainable.
155
156	---
157
158	## Workflow
159
160	### Step 1: Audit current state
161
162	- What docs exist?
163	- Where do they live? (often: scattered)
164	- Who owns each?
165	- How fresh are they?
166	- Are they actually used? (check page views or referrals if measurable)
167
168	The audit is often eye-opening. Most teams have more docs than they realize, in more places than they realize.
169
170	### Step 2: Categorize and tier
171
172	For each doc:
173	- Category (reference / how-to / explanation / tutorial)
174	- Tier (customer / shared / team / scratchpad / generated)
175
176	Some docs are mixed. Note the dominant category.
177
178	### Step 3: Identify gaps
179
180	What documentation does the team need that doesn't exist?
181
182	Common gaps:
183	- "How does X actually work?" no answer
184	- Onboarding for the role no one's onboarded recently
185	- Runbook for a system that's never broken (yet)
186	- Decision rationale for "why are we doing it this way"
187
188	Ask people what they wish were documented. They know.
189
190	### Step 4: Identify dead weight
191
192	Docs that are:
193	- Out of date and not getting updated
194	- Duplicated across places (one is canonical, others should redirect or be deleted)
195	- About things that no longer exist
196	- Drafts abandoned long ago
197
198	Delete or archive. Stale docs are worse than missing docs (people might trust them).
199
200	### Step 5: Pick the home(s)
201
202	Where docs live affects whether they're maintained.
203
204	Common locations:
205	- Code repo (markdown): for docs tightly coupled to code (READMEs, ADRs, runbooks for the service)
206	- Wiki / Notion / Confluence: for cross-team and team-internal
207	- Docs site (Docusaurus, Mintlify, custom): for customer-facing
208	- Tickets / decision logs: for ephemeral records
209
210	Don't aim for one home. Aim for a clear answer to "where does this kind of doc live?"
211
212	### Step 6: Establish ownership
213
214	Every doc has an owner. Without an owner, it goes stale.
215
216	Owner can be:
217	- A team
218	- A role (the on-call rotation, the PM, the EM)
219	- A person, with a backup
220
221	If an owner isn't obvious, the doc may not deserve to exist.
222
223	### Step 7: Establish maintenance cadence
224
225	Per tier:
226
227	\| Tier \| Review cadence \|
228	\|---\|---\|
229	\| Customer-facing \| Per release, plus quarterly \|
230	\| Cross-team \| Quarterly \|
231	\| Team-internal \| Quarterly \|
232	\| Personal scratchpad \| None \|
233	\| Auto-generated \| On every change \|
234
235	Maintenance includes:
236	- Verify accuracy
237	- Update for changed systems
238	- Archive what's no longer relevant
239	- Address user feedback
240
241	### Step 8: Make doc updates part of work
242
243	Documentation isn't a separate project. It's part of the work that produces it.
244
245	- New feature: docs are part of the feature
246	- New process: doc is part of the rollout
247	- Decision made: ADR or decision-log entry filed
248	- Bug postmortem: runbook updated
249	- New hire: onboarding doc updated based on their experience
250
251	The team that ships features without docs has less than they think they have.
252
253	### Step 9: Make docs discoverable
254
255	Even great docs are useless if no one finds them.
256
257	- Search that actually works (most platforms; some better than others)
258	- Index pages for major topics
259	- Cross-links between related docs
260	- Search aliases for common alternative phrasings
261	- Pinning the most-used docs
262
263	### Step 10: Measure
264
265	What's measurable depends on the platform:
266	- Page views
267	- Search queries (and zero-result queries)
268	- "Was this helpful?" feedback
269	- Time on page
270	- Referral patterns
271
272	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).
273
274	---
275
276	## Specific patterns
277
278	### README per project
279
280	Every code repo has a README that answers:
281	- What is this?
282	- How do I run it?
283	- How do I contribute?
284	- Where do I find more info?
285
286	Five sentences each, often. Length isn't the goal. The READ-it-ME promise is.
287
288	### ADR (Architecture Decision Record)
289
290	Per significant decision:
291
292	```
293	# ADR-NNN: [Title]
294
295	Status: [Proposed / Accepted / Deprecated / Superseded]
296	Date: [Date]
297
298	## Context
299	[What's the situation? What forces are at play?]
300
301	## Decision
302	[What was decided?]
303
304	## Consequences
305	[What happens because of this decision? Both good and bad.]
306	```
307
308	ADRs accumulate. They become the explanation layer for "why are we doing it this way."
309
310	### Runbook
311
312	Per system:
313	- What it is
314	- How to access it
315	- Common operations (with commands)
316	- Common failure modes
317	- Restore from backup procedure
318	- Escalation contacts
319
320	See `incident-response` and `backup-and-disaster-recovery` for runbook standards.
321
322	### Onboarding pathway
323
324	Per role:
325	- Day 1
326	- Week 1
327	- Month 1
328	- 90 days
329
330	See `team-onboarding-playbook`.
331
332	### Decision log
333
334	Lightweight version of ADRs. Date, decision, decider, why. Keeps a record without ceremony.
335
336	### Glossary
337
338	Terms that have specific meaning in the team or product. Reduces confusion. Trains AI tools too (more on that later).
339
340	---
341
342	## Tooling
343
344	The tool is less important than the discipline. That said:
345
346	\| Tool category \| Examples \| Best for \|
347	\|---\|---\|---\|
348	\| Wiki \| Notion, Confluence, GitBook \| Cross-team, internal \|
349	\| Markdown in code \| GitHub, GitLab, Bitbucket \| READMEs, ADRs, technical \|
350	\| Docs sites \| Docusaurus, Mintlify, ReadMe \| Customer-facing, public docs \|
351	\| Internal sites \| MkDocs, custom \| Team-specific patterns \|
352
353	Considerations:
354	- Search quality (a poor search makes everything worse)
355	- Editor quality (people won't write in painful editors)
356	- Version control (can you see history?)
357	- Permissions (right people can read and write)
358	- API and integration (for automation)
359	- Cost at your scale
360
361	For small teams: a single wiki tool is plenty. For larger: tiered tools.
362
363	---
364
365	## AI-related notes
366
367	LLMs and AI assistants increasingly read documentation. Some considerations:
368
369	- Clear, consistent structure helps both humans and AI
370	- A glossary of terms helps both
371	- File-level metadata (front matter) helps tools
372	- Public docs may be read by AI crawlers; consider an `llms.txt` if relevant
373	- AI-generated drafts are a starting point, not a final answer; humans review
374
375	---
376
377	## Failure patterns
378
379	Documentation as a "later" task. Always written later. Later means never. Make docs part of the work.
380
381	One mega-doc for everything. Wiki page that's 8,000 words. No one reads it. Break by category and topic.
382
383	Stale docs that nobody trusts. "Probably out of date" is the thought that kills documentation. Either keep current or archive.
384
385	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.
386
387	Wikis that are graveyards. Lots of pages, no one trusts any of them. Audit, archive, restart with a slimmer set.
388
389	Docs separated from code. API docs in a wiki, code in a repo. They drift. Co-locate.
390
391	Docs without examples. Reference without examples is hard to use. Examples make it concrete.
392
393	Examples that don't run. Code examples that worked once, drifted. Test examples in CI where possible.
394
395	Long-form when reference would do. A 2,000-word doc explaining what a 30-row table would. Use the right form.
396
397	Multiple sources of truth. Same info in three places, all slightly different. Pick canonical, redirect others.
398
399	Doc tools no one uses. Adopted because of a feature; team doesn't actually use it. Pick tools the team will use.
400
401	Doc style guide that's longer than the docs. Process beats product. Guide should be short.
402
403	No way to mark docs as deprecated. Old docs sit alongside current ones with no indication. Add a "deprecated" or "archived" status.
404
405	No analytics. No idea what's being used or what's missing. Even basic page views inform priorities.
406
407	Docs that read like specifications. Dense, formal, hard to scan. Write for the reader.
408
409	---
410
411	## Output format
412
413	A documentation strategy document includes:
414
415	- Audit: what exists, where, in what state
416	- Tiering and categorization: the framework applied to existing docs
417	- Gap list: what should exist but doesn't
418	- Tool decisions: where each kind of doc lives
419	- Ownership map: who owns what
420	- Maintenance cadence: what's reviewed when
421	- Style guide (brief): consistency standards
422	- Roadmap: prioritized work to fill gaps and close out dead weight
423
424	---
425
426	## Reference files
427
428	- [`references/doc-types-guide.md`](references/doc-types-guide.md): Detailed guide to the four doc types (reference, how-to, explanation, tutorial) with examples and templates for each.
429

View all files on GitHub →

Details

Updated: Sep 15, 2026
License: MIT
Stars on the repo: ★ 901
Checked: Sep 24, 2026
Source: rampstackco/claude-skills ↗
Creator: rampstackco · 60 listings

View creator

Made with documentation-strategy

Documentation strategy — Showcase grid filtered by Tone equals Provocative and Sensory equals Resonant, showing eight matching brand cards with… (from the rampstackco/claude-skills README)

by rampstackco

Documentation strategy — Showcase grid with all four axis filters set to Provocative, Editorial Restrained, Coach, and Resonant, showing zero… (from the rampstackco/claude-skills README)

by rampstackco

Documentation strategy — RampStack architecture diagram. A central navy hub card shows the RampStack mark with the subtitle 'Stack-agnostic… (from the rampstackco/claude-skills README)

by rampstackco