Documentation
Documentation is a product interface for future maintainers. It should preserve contracts, operating knowledge, and decisions that code alone cannot explain. The best format depends on the job: tutorials teach a path, how-to guides solve a task, reference docs define complete contracts, and explanations preserve the model behind a system.
Owners, source of truth, and freshness
Useful engineering documentation has an owner, a source of truth, and a freshness rule. API docs should live near API design schemas. Runbooks should name alerts, dashboards, rollback commands, and escalation paths for production integration. Decision records should link to technical decision records, not duplicate their reasoning. Requirements docs should carry acceptance criteria from requirements engineering.
Feature documentation checklist
For a feature document, a reviewer can check a small contract instead of reading free-form prose:
| required field | example value |
|---|---|
| owner | search-platform |
| source table | events.ticket_views |
| refresh | hourly at minute 10 |
| null semantics | missing user_id means no personalized features |
| backfill | recompute by event_date, maximum 31 days |
| consumers | ticket-triage-v2, agent-assist-v1 |
No required fields are missing, and two consumers are named. This is a documentation contract, not just prose. The same idea supports testing: a fixture can assert that a contract file contains required fields.
Failure modes
Documentation fails when it copies code, lacks an owner, or mixes current behavior with future intent. Stale docs should be fixed or deleted; preserving misleading prose is worse than having no doc. Repeated code review questions are strong candidates for a short checklist or reference page.
References
Nav