Documentation strategy.

The framework

Four documentation types. Do not conflate them.

Different categories of doc serve different purposes; this is the Diátaxis split, well-known in technical writing.

1. 01Reference: what things are, looked up when needed. API references, configuration options, glossaries, architecture diagrams. Comprehensive, accurate, searchable, stable.
2. 02How-to: how to do a specific task, procedural. Step-by-step, tested by someone who did not write it, with prerequisites and troubleshooting.
3. 03Explanation: why things are the way they are, conceptual. Architecture rationale, decision records, strategy docs. Narrative, capturing the why and the context.
4. 04Tutorial: learning-oriented, from zero to capable. Sequenced from simple to complex, hands-on, assuming no prior knowledge, with clear completion criteria.

Pairs with these platforms

Where docs live affects whether they stay current.

The tool matters less than the discipline, but docs live somewhere, and the home shapes whether they get maintained. A wiki like Notion holds cross-team and team-internal docs; GitHub holds the markdown that should travel with the code: READMEs, decision records, and service runbooks, co-located so they do not drift from what they describe.

• Notion-centric teams

  Notion

  Briefs as a queryable database

  Open the page

• Engineering teams

  GitHub

  Briefs as design-system source of truth

  Open the page

Bridges to other skills

Where the writing and the onboarding live.

Documentation strategy designs the system. These cover the writing inside it and the adjacent work it overlaps.

• Writes a doc

  content-and-copy

  Writing the actual content of a single document is a content-and-copy task. This skill decides what gets documented, where, and how it stays fresh.

• Customer KB copy

  content-strategy

  Customer-facing knowledge base copy as a content program belongs with content strategy. Documentation strategy covers the internal and product-doc system.

• Onboarding docs

  team-onboarding-playbook

  Onboarding pathways are a shared concern; run it alongside this skill so the day-1-to-90-day docs are part of the documentation system, not a separate island.

• Inline docs

  code-review-web

  Code comments and inline documentation are reviewed there. Documentation strategy handles the docs that sit beside the code, not the comments inside it.

Frequently asked questions.

What are the four documentation types?

The Diátaxis split: reference (what things are, looked up when needed, such as API references and configuration options), how-to (procedural, step-by-step task instructions), explanation (why things are the way they are, conceptual, such as architecture rationale and decision records), and tutorial (learning-oriented, walking someone from zero to capable). Conflating them is how docs get bad: a tutorial that tries to also be a comprehensive reference serves neither purpose well.

What are the five documentation tiers?

Customer-facing (public docs and API references, high visibility, slow change, editorial review, tied to release), cross-team and shared, team-internal, personal scratchpad (notes and drafts, low maintenance, not linked from official docs), and auto-generated (derived from code, regenerated in CI). The tiering matters because the maintenance bar differs by tier; asking team-internal docs to meet customer-facing standards is wasteful and unsustainable, and the cadence ranges from per-release for customer docs down to none for scratchpads.

Why do docs go stale?

Most often because no one owns them. Every doc needs an owner: a team, a role (the on-call rotation, the PM, the EM), or a person with a backup. Without an owner, a doc goes stale, and if an owner is not obvious, the doc may not deserve to exist. Stale docs are worse than missing docs, because people might still trust them, so the rule is to keep a doc current or archive it, with an explicit deprecated or archived status rather than letting old docs sit silently beside current ones.

How do I keep documentation from being a 'later' task?

Make doc updates part of the work that produces them, not a separate project. A new feature's docs are part of the feature, a new process's doc is part of the rollout, a decision files an architecture decision record or a decision-log entry, a postmortem updates the runbook, and a new hire's experience updates the onboarding doc. Documentation written 'later' means documentation written never, and the team that ships features without docs has less than it thinks it has.

Where should docs live?

Not in one single place; aim instead for a clear answer to 'where does this kind of doc live?' Put markdown in the code repo for docs tightly coupled to code (READMEs, decision records, service runbooks), a wiki like Notion for cross-team and team-internal docs, a docs site for customer-facing material, and decision logs for ephemeral records. Co-locate code docs with the code so they do not drift, and avoid multiple sources of truth: pick a canonical home and redirect the rest.

How do I know the documentation is working?

For internal docs, the most useful measure is qualitative: are the same questions getting asked over and over? If they are, the docs either do not exist, are not found, or are not clear. Where the platform allows it, basic signals help set priorities: page views, search queries (especially zero-result ones, which name the gaps), and 'was this helpful' feedback. Discoverability is half the battle, so invest in working search, index pages, cross-links, and pinning the most-used docs.