Skip to content

Writing docs

HQ is useful only if it stays closer to reality than memory or chat history.

Page contract

Important pages should declare:

---
owner: GitHub handle or team
status: proposed | accepted | verified | deprecated
reviewed: YYYY-MM-DD
---

Write for reconstruction

Assume the reader has none of the conversation that produced the page. Include the goal, observable current state, constraints, decision, evidence, and next action.

Update in the same change

When behavior changes, update its documentation in the same pull request. When ownership or roadmap state changes, update HQ and GitHub together.

Avoid

  • Status words without evidence
  • Dates with no owner or acceptance condition
  • Copying secrets or production credentials
  • Architectural diagrams that disagree with deployed reality
  • Pages that have no owner and never expire