These guide decisions across new documentation, updates, audits, rewrites and larger restructures. They are meant to be applied together rather than as isolated rules, and two of them pull against each other often enough that the next section exists purely to settle it.
- Start with user intent. Begin with what the user is trying to do, not with the feature being documented. Ask whether they want to learn, complete a task, look something up, or understand something better. This also means questioning whether a requested new page is needed at all.
- Give every document one primary job. Each document should have one clear reason to exist. Supporting material from another type is acceptable. Substantial secondary purposes should be separated.
- Make documentation sufficiently self-contained. A user should not need to go and research something before they can even follow the page. That does not mean explaining everything from first principles: it means enough context, prerequisites and orientation for the intended reader. Where deeper background helps but is not essential, link to it.
- Prefer one authoritative answer. Update an existing page where it already serves the same user need. Create a separate document only when it solves a meaningfully different problem.
- Split by user need, not by length. Length can indicate a problem but it does not identify what the problem is. Keep related material together when separating it would make the task harder.
- Reduce unnecessary navigation. Use links where they help, but do not force users through several pages to complete one routine task. Short, stable information can be repeated when doing so removes a pointless click.
- Write for the intended reader. Do not assume the same knowledge across every document. State prerequisites when missing them would block someone. Explain unfamiliar concepts briefly when needed. Avoid teaching basics the intended reader can be expected to have. The aim is neither to over-explain nor under-explain.
- Verify every technical claim. Documentation should describe what the product actually does. Test procedures where reasonably possible, and flag what could not be verified rather than treating a plausible source as proof.
- Maintain documentation as product content. Publication is not the end of the work. A product change should trigger a review of the affected page and everything related to it.
- Choose usefulness over purity. The method exists to improve documentation, not to force every page into a perfect theoretical category. Where a strict reading would make the docs harder to use, apply editorial judgement.
The final test is always practical: does this structure make the documentation easier for the intended user to find, understand and use?
