What you build
Living documentation that stays close to reality:
- Runbooks with steps, checks, and escalation paths operators can follow under stress.
- README and onboarding that match the repo today—not last year’s screenshot.
- API or config docs derived from sources of truth (OpenAPI, schemas, code comments) where possible.
The outcome is trust: people open the doc first because it is usually right.
Why CoWork OS is a strong fit
- Agents can traverse the repo and tickets to propose updates when behavior changes.
- Structured skills help enforce headings, tone, and required sections (SLOs, owners, links).
- Human approval before publishing to a customer-facing site or status page fits how docs should ship.
How to use
- Pick one doc that hurts most when wrong (on-call runbook, public API intro).
- Define audience and non-goals (what this page will not cover).
- Pull facts from code, config, or design docs; label anything inferred as “verify.”
- Diff proposed text against the current page; reject vague filler.
- Owner and review cadence—who re-validates after the next release?
Prerequisites
- A canonical location for docs (repo path, wiki, CMS).
- Style guide or example page the team likes.
- Permission to edit the target system or open PRs against it.
Steps
- Inventory stale sections (wrong commands, old URLs, missing owners).
- Draft outline only; agree on structure before prose.
- Fill sections from primary sources; cite paths or ticket IDs.
- Peer review with someone who runs the procedure monthly.
- Schedule a re-check tied to the next release train.
Suggested prompts
- “Compare this runbook to script X and config Y; list mismatches only.”
- “Rewrite for on-call at 3am: short sentences, no jargon without definitions.”
- “Add a troubleshooting section from the last three incidents linked here.”
Avoid generic “improve the docs” without a target reader and scenario.
Launch readiness
- Commands in the doc run on a clean machine or container as written.
- Owners, SLAs, and escalation contacts are current.
- Links resolve; code blocks use tested paths or are clearly placeholders.
Common pitfalls
- Polished but wrong—good prose that does not match production.
- Duplicated truth across wiki and repo with no single owner.
- Docs-only releases—shipping words without verifying behavior.
- Jargon without glossary for new teammates.