documentation-strategy
This skill helps teams establish documentation systems by determining what gets documented, where it lives, who maintains it, and how to keep it current. Use it when auditing existing docs, choosing documentation platforms, designing maintenance processes, fixing scattered or outdated documentation, or addressing repeated questions during onboarding.
git clone --depth 1 https://github.com/rampstackco/claude-skills /tmp/documentation-strategy && cp -r /tmp/documentation-strategy/dist/pi/.agents/skills/documentation-strategy ~/.claude/skills/documentation-strategySKILL.md
# 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 | Re
Run a comprehensive WCAG accessibility audit covering perceivable, operable, understandable, and robust principles. Use this skill whenever the user wants to audit accessibility, review WCAG compliance, fix accessibility issues, prepare for accessibility certification, address an accessibility lawsuit risk, or systematically improve a site's accessibility. Triggers on accessibility audit, WCAG audit, a11y audit, accessibility compliance, ADA compliance, screen reader test, keyboard navigation, accessibility report, fix accessibility, axe scan. Also triggers when accessibility issues have been reported and need systematic remediation.
How to produce ad creative that converts at performance scale. Hook patterns, format selection, video pacing, variation systems, sequential testing methodology, fatigue detection, brand-voice alignment without conversion dilution, and platform-specific creative norms. Triggers on ad creative, ad design, hook patterns, ad video pacing, creative testing, ad variations, creative refresh, creative fatigue, refresh ad creative, video ads for Meta, TikTok creative, LinkedIn ad creative, ad asset library. Also triggers when a team is producing creative at scale, planning a creative test cycle, or auditing why creative is not converting.
How to read paid media dashboards without fooling yourself. Attribution models, platform reporting quirks, multi-platform reconciliation, ROAS vs LTV horizon traps, statistical noise in performance metrics, incrementality testing, and the failure modes that produce expensive lessons. Triggers on read paid media dashboard, attribution analysis, ROAS vs LTV, multi-platform reconciliation, ad incrementality, geo holdout, conversion lift study, ghost bidding, paid media reporting, board-deck paid media metrics, blended CAC, MMM, MTA, last-click attribution. Also triggers when a marketer is about to scale, kill, or rebudget a campaign based on platform metrics, or when reconciling platform reports against warehouse revenue.
Run a structured after-action review (postmortem, retrospective) on a launch, incident, or completed project to capture timeline, root cause analysis, contributing factors, and actionable lessons. Use this skill whenever the user wants to run a postmortem, retrospective, AAR, or after-action review on any past event. Triggers on after-action report, AAR, postmortem, retrospective, retro, post-incident review, what went well what didn't, lessons learned, blameless postmortem, root cause analysis, RCA, five whys. Also triggers when the user has just shipped something or just resolved an incident and wants to capture learnings.
How humans and AI compose in content workflows. Where AI legitimately participates, where humans must own, hybrid workflow patterns, voice ownership preservation, the AI slop problem, disclosure and transparency, team calibration, and the ethics of intellectually honest AI-assisted content production. Triggers on AI content workflow, AI-assisted writing, hybrid content production, AI in editorial, AI slop, AI disclosure, AI usage policy, AI content ethics, voice preservation with AI, team AI calibration. Also triggers when content feels generic despite quality tools, when team AI usage has drifted into inconsistency, or when a regulated or trust-sensitive context requires explicit AI policy.
Design measurement frameworks including event taxonomy, KPI hierarchy, dashboard architecture, attribution models, and analytics implementation strategy. Use this skill whenever the user wants to plan analytics, design dashboards, build event taxonomies, define KPIs, set up tracking, or audit existing measurement. Triggers on analytics strategy, measurement plan, event taxonomy, tracking plan, KPI framework, dashboard design, north star metric, attribution model, conversion tracking, GA4 setup, Mixpanel setup, analytics audit. Also triggers when the user has data but no clear way to use it, or wants to make decisions but doesn't know what to track.
Direct visual and creative work for campaigns, photography, illustration, video, and branded experiences. Use this skill whenever the user wants to brief a photographer, direct illustrators, plan a creative campaign, develop visual concepts, write a creative direction document, or evaluate creative work for fit. Triggers on art direction, photo brief, photography brief, illustration brief, campaign concept, creative concept, visual direction, mood board, look and feel, visual treatment, video direction. Also triggers when the user has approved brand identity but needs to extend it into specific creative deliverables.
Plan and run backups, set recovery objectives, and run disaster recovery drills. Use this skill when defining RPO/RTO targets, designing backup architecture, deciding what to back up and how often, planning for full-region or platform outages, or running a restoration drill. Triggers on backup, restore, RPO, RTO, disaster recovery, DR, business continuity, what if the database is gone, what if our hosting goes down, recovery drill, ransomware planning. Also triggers when an incident reveals a gap in restoration capability.