# Pc Documentation

> Use when a feature, architecture decision, incident, or workflow change needs durable technical documentation such as tutorials, reference docs, ADRs, runbooks, or maintenance guidance instead of ad hoc notes.

- Skill: `yknothing/pc-documentation` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add yknothing/pc-documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yknothing/pc-documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: yknothing (https://skillmd.com/u/yknothing)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yknothing/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](references/context.md).

## Diataxis Framework

Organize documentation into four types:

| Type | Purpose | Oriented to |
|------|---------|-------------|
| **Tutorial** | Learning-oriented | Getting started, step-by-step |
| **How-to Guide** | Task-oriented | Solving specific problems |
| **Reference** | Information-oriented | Technical descriptions (API docs) |
| **Explanation** | Understanding-oriented | Background, context, decisions |

## Inputs

[I/O contract notes](references/io-contract.md) 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.

## Distribution

- Public install surface: `skills/.curated`
- Canonical authoring source: `skills/cross-cutting/pc-documentation/SKILL.md`
- This package is exported for `npx skills add/update` compatibility.
- Packaging stability: `beta`
- Capability readiness: `beta`
- Portability: `portable_with_caveat`
- Public caveat: Portable as skill guidance; full governance guarantees require the Prodcraft repository contracts and validation checks.