Pc Documentation

Documentation

Documentation is a product. Treat it with the same care as code: version it, review it, test it, maintain it.

Context

Documentation is a cross-cutting concern that applies at every lifecycle phase.

See context notes.

Diataxis Framework

Organize documentation into four types:

Inputs

I/O contract notes define required inputs and authority.

Process

Step 1: Identify the Need

What documentation is needed? Common triggers:

• New feature shipped (how-to guide for users)
• Architecture decision made (ADR for future developers)
• Incident resolved (runbook to prevent recurrence)
• New team member joining (onboarding tutorial)

Before writing, classify the need explicitly:

• must_consider only: verify that no durable doc update is needed and record that decision in the surrounding artifact or handoff
• must_produce: create or update the durable doc because downstream work, operators, or users would otherwise lose context
• skip_when_fast_track: only use the waiver when the route is explicitly fast-tracked and the change does not create durable knowledge debt

Step 2: Write for Your Audience

• Developers: Code examples, API reference, architecture docs
• Operators: Runbooks, deployment guides, monitoring dashboards
• Users: Tutorials, how-to guides, FAQs
• Stakeholders: Architecture Decision Records, design docs

Step 3: Keep Docs Close to Code

• Use docs-as-code: Markdown in the repository, versioned alongside code
• Auto-generate API docs from code annotations (OpenAPI, JSDoc, docstrings)
• README.md in every significant directory explaining its purpose
• Architecture Decision Records in docs/adr/

Step 4: Review and Maintain

• Documentation reviews as part of PR process (if docs were changed)
• Quarterly documentation audit: remove outdated content
• Track documentation debt alongside tech debt

Outputs

Produce only declared outputs at their documented quality boundary.

Quality Gate

• Target audience can complete their task using only the documentation
• Documentation is discoverable (linked from README, searchable)
• Auto-generated docs are integrated into CI pipeline
• No outdated information (verified within last quarter)

Anti-Patterns

1. Write once, abandon forever -- Outdated docs are worse than no docs. They mislead.
2. Documentation dump -- A 200-page doc no one reads. Keep it focused and findable.
3. Separate documentation system -- If docs aren't next to code, they won't be updated with code.
4. No documentation at all -- "The code is self-documenting" is only true for WHAT, never for WHY.