new-guide

Writing a new user-facing guide in the correct Diátaxis quadrant requires defining an audience contract for reader posture before drafting body text from a quadrant-specific scaffold, ensuring the page stays purely tutorial, how-to, reference, or explanation.

The Diátaxis framework structures documentation into four distinct quadrants—tutorials, how-to guides, reference, and explanation—matching each page to a specific reader posture to prevent mixing modes and confusing the audience.

Split documentation into a separate page instead of mixing modes when adjacent material belongs to a different Diátaxis quadrant, applying link-out discipline to cross-link existing sibling pages rather than blending reference and tutorial content together.

Structure a tutorial versus a reference page for shipped features by establishing an audience contract for reader posture, then applying a template-driven scaffold that keeps tutorials action-oriented and reference pages neutral without blending adjacent forms.

You do not need existing sibling pages before writing a new guide, but cross-link checks only add links to sibling pages that already exist within the repository, ensuring your new documentation connects safely without creating broken links.