fleet-doc-lifecycle

How the technical writer maintains documentation as a living system — staleness detection, proactive page maintenance, complementary work alongside architect/engineer/UX

SKILL.md

GitHub

Documentation Lifecycle

The Principle

Documentation is a LIVING SYSTEM — alongside code, not after it. When features are built, documentation updates in parallel. When architecture decisions are made, they're recorded. When deployments change, runbooks update.

You don't wait for explicit "write docs" tasks. In full-autonomous mode, you PROACTIVELY keep documentation current.

Three Contribution Points

Before Implementation (reasoning stage)

When you receive a documentation_outline contribution task:

  1. Call writer_doc_contribution(task_id) — gathers context
  2. Read the verbatim requirement
  3. Determine: what sections, what audience, what content level
  4. Deliver: fleet_contribute(task_id, "documentation_outline", outline)

The outline helps the implementing agent understand what documentation is expected alongside their code.

During Implementation (complementary)

For complex features, work alongside the engineer:

  • Read their commits and PR descriptions as source material
  • Start documentation drafts they can review for accuracy
  • Record architecture decisions as they're made (complement architect)
  • Document interaction patterns as they're defined (complement UX)

After Implementation (completion chain)

When a feature completes:

  • Call writer_staleness_scan() — identifies done tasks needing docs
  • Read the PR, completion summary, and artifacts
  • Produce or update documentation pages
  • Update Plane pages if connected

Staleness Detection

Every heartbeat in full-autonomous mode:

What's Stale?

  • Feature completed in sprint S4 but documentation last updated in S2 → stale
  • Task "Add CI/CD" completed but no deployment page exists → missing
  • Architecture decision made but not recorded → undocumented

How to Detect

Call writer_staleness_scan() — lists done tasks that may need docs. Cross-reference against existing documentation. Flag gaps.

How to Fix

Don't just update — improve. Each documentation touch should make the page MORE useful, not just less outdated.

Documentation Quality Standards by Phase

Phase What's Needed
poc README with setup instructions. That's it.
mvp Setup guide, usage examples, API docs for public endpoints
staging Full docs: API reference, deployment guide, troubleshooting, runbook
production Everything: architecture overview, API reference, deployment, troubleshooting, runbook, changelog, migration guides

What Good Documentation Looks Like

Structure

  1. What — what does this feature/system do? (1 paragraph)
  2. Setup — how to install/configure (step by step, copy-pasteable)
  3. Usage — how to use it (with realistic examples)
  4. API — endpoints/functions (parameters, responses, errors)
  5. Troubleshooting — common issues and solutions
  6. Architecture — how it works internally (for maintainers)

Audience Awareness

  • User docs: someone who wants to USE the feature
  • Ops docs: someone who needs to DEPLOY or MAINTAIN it
  • Dev docs: someone who needs to MODIFY or EXTEND it

Different audiences, different content. A README serves users. A runbook serves ops. An architecture doc serves devs.

Terminology Consistency

Maintain consistent terminology across all documentation surfaces. If the codebase calls it "task_readiness", don't call it "progress" in docs. If the PO says "delivery phase", don't call it "maturity level" in docs.

Group Calls

Call When
writer_doc_contribution(task_id) Contribution task — produce documentation outline
writer_staleness_scan() Heartbeat — identify tasks needing documentation

Complementary Work

With What You Do
Architect Record architecture decisions, design rationale, ADRs
Engineer Document APIs, usage examples, configuration
UX Document interaction patterns, user flows, state diagrams
DevOps Document deployment procedures, runbooks, monitoring
PM Sprint reports, changelog generation