Documentation is part of the service. A user-visible behavior change is incomplete until its canonical guide reflects what the product actually does.
Write for the question
- Lead with the answer or next action.
- Use familiar words, direct sentences, active voice, and sentence-case headings.
- Put resident and routine operator tasks before architecture.
- Separate tutorials, goal-oriented guides, explanation, and reference.
- State what is true now; label planned, legacy, and retired behavior.
- Update the existing canonical page instead of creating a competing explanation.
Layer technical detail
Technical readers need stable contracts, trust boundaries, data-flow concepts, and known user-visible limitations. They do not need private source annotations, production identifiers, raw schemas, exact recovery steps, or implementation playbooks on a public site.
When uncertain, publish the observable guarantee and keep the mechanism private.
Use visuals deliberately
Use a diagram when several components or decisions interact, a table for repeated exact mappings, and a screenshot only when recognizing the interface matters. Screenshots must be current, deliberately staged or sanitized, and reviewed for names, messages, addresses, browser chrome, and hidden metadata.
Accessibility
- Give every image meaningful alternative text.
- Preserve heading order and descriptive link text.
- Do not use color as the only signal.
- Check keyboard focus, narrow-screen layout, reduced motion, and print behavior.
- Prefer standard Markdown so the same page remains usable in Obsidian.
Publication boundary
Confidential design records and maintainer runbooks live in a separate private knowledge base. Hiding a folder from navigation, marking a page draft, or omitting a link is not a confidentiality boundary.
See security-and-privacy and stewardship.