AI Skill Report Card
Governing Documentation
Documentation Governor
Quick Start13 / 15
Given a project or product, produce four artifacts in this order:
- Documentation Tree — hierarchical map of all doc categories and files
- Version Strategy — how docs are versioned, tagged, and deprecated
- Knowledge Structure — ownership, cross-linking, and single-source-of-truth rules
- Maintenance Plan — cadence, triggers, and responsibilities for keeping docs current
Example invocation: "Set up documentation governance for our API platform with public docs, internal runbooks, and architecture decision records."
Recommendation▾
Add a third example showing a bad/anti-pattern output (e.g., team-organized tree) to reinforce contrast, since current examples only show good outcomes
Workflow14 / 15
Progress:
- Step 1: Inventory existing documentation (types, locations, owners, last-updated dates)
- Step 2: Identify audiences (external users, internal engineers, new hires, stakeholders)
- Step 3: Build the Documentation Tree grouped by audience/purpose, not by team
- Step 4: Define Version Strategy (semantic vs. date-based, deprecation policy, changelog rules)
- Step 5: Define Knowledge Structure (canonical sources, cross-reference rules, naming conventions)
- Step 6: Define Maintenance Plan (review cadence, staleness triggers, ownership matrix)
- Step 7: Flag consistency risks (duplicated content, conflicting terminology, orphaned pages)
Step 3 details — Documentation Tree
Structure as a nested outline, max 3-4 levels deep:
/docs
/getting-started
/architecture
/decision-records (ADR-XXX format)
/diagrams
/api-reference (auto-generated, versioned)
/runbooks
/governance (this doc's own meta-docs: style guide, templates)
Mark each node with: owner, audience, update trigger.
Step 4 details — Version Strategy
Recommend by default:
- Semantic versioning (
vMAJOR.MINOR) for anything tied to a shipped product/API - Date-stamped (
YYYY-MM-DD) for runbooks, meeting notes, and living guides - Every doc carries a header:
Version | Last Reviewed | Status (Draft/Active/Deprecated) - Deprecated docs redirect to successor, never deleted outright for 1 release cycle
Step 5 details — Knowledge Structure
- One canonical source per concept; all other mentions link back, never duplicate
- Naming convention:
[Category]-[Topic]-[Subtopic].md - Cross-link using relative paths, validate links on each review cycle
- Terminology glossary is mandatory and referenced, not restated, elsewhere
Step 6 details — Maintenance Plan
- Review cadence: high-churn docs (API reference) reviewed per release; low-churn (architecture) reviewed quarterly
- Staleness trigger: auto-flag any doc unreviewed for >90 days
- Ownership matrix: each doc node has exactly one accountable owner (not a team)
- Broken-link and orphan-page audit scheduled monthly
Recommendation▾
Include a concrete template snippet (e.g., full doc header format or ownership matrix table) rather than just describing it prose-style
Examples15 / 20
Example 1: Input: "We have scattered README files, a Notion wiki, and Slack pinned messages for a mid-size SaaS product." Output:
- Documentation Tree: consolidates into
/docswith nodes forproduct-overview,api-reference,internal-runbooks,architecture-decisions,onboarding - Version Strategy: API reference gets semver tied to release tags; runbooks get date-stamped headers
- Knowledge Structure: Notion wiki becomes canonical for onboarding only; Slack messages get migrated or archived with no standing authority
- Maintenance Plan: monthly staleness audit, owner assigned per node, quarterly architecture review
Example 2: Input: "Single technical writer, small startup, just needs a lightweight structure before it gets messy." Output:
- Documentation Tree: flat 2-level structure (
/docs/product,/docs/internal) - Version Strategy: date-stamped only, no semver until first public release
- Knowledge Structure: single glossary file, all docs link to it
- Maintenance Plan: lightweight — writer self-reviews monthly, no formal ownership matrix needed yet
Recommendation▾
Address edge cases like multi-team ownership conflicts or migrating legacy docs with no clear owner
Best Practices
- Always separate audience-facing docs from internal-only docs at the top tree level
- Enforce "one canonical source" ruthlessly — duplication is the primary cause of drift
- Tie version strategy to real triggers (releases, decisions) not arbitrary calendar dates alone
- Keep the maintenance plan proportional to team size — don't impose enterprise process on a 3-person team
- Always output a glossary/terminology node; inconsistent terms are the most common consistency failure
Common Pitfalls
- Don't organize the tree by internal team structure — organize by audience and purpose
- Don't recommend deleting deprecated docs immediately — redirect and sunset instead
- Don't propose the same review cadence for all doc types — high-churn and low-churn docs need different cycles
- Don't skip the ownership matrix — "owned by the team" always decays into owned by no one
- Don't over-engineer versioning for early-stage projects with no external consumers yet