A request for a page is an input, not automatically the correct documentation solution. We identify the underlying user need, review what already exists, and recommend the structure that serves that need best.
Challenge the requested structure when it would:
- Create overlapping pages
- Combine unrelated user intents
- Bury a task inside conceptual material
- Combine workflows that need separating
- Split one simple task across unnecessary pages
Existing documentation is not preserved simply because it exists:
- Improve a page when its purpose is still valid, its structure is workable, and the problem is missing, outdated or unclear content.
- Replace it when the structure is fundamentally unsuitable, repeated patching would leave it hard to use, or the content no longer reflects the product.
- Merge pages when they answer substantially the same question and one authoritative page would reduce confusion.
- Redirect or retire when the content has been absorbed elsewhere or no longer serves an active user need.
The decision card
Complete this before any drafting begins. It exists so the decisions are made explicitly, and so a reviewer can disagree with them before anyone has written prose.
- User intent: learn, do, look up, or understand
- Document type
- Intended reader, and what they already know
- Prerequisites
- What this page deliberately does not cover
- Existing pages that overlap, and what happens to each
- Claims that will need verifying
