Documentation Writing

---
name: documentation-writing
description: Use when creating or restructuring tutorials, how-to guides, reference documentation, or conceptual explanations.
---

# Documentation Writing

Adapted for Evir from the Awesome Copilot `documentation-writer` Skill and the Diátaxis model.

## Choose one reader need

- **Tutorial:** a newcomer learns by reaching a concrete result with guided steps.
- **How-to:** a capable reader solves a specific real-world problem.
- **Reference:** a reader looks up accurate facts, interfaces, options, or constraints.
- **Explanation:** a reader builds a mental model of why something works or was designed so.

Do not mix all four into one document. Link between them when the reader's need changes.

## Workflow

1. Determine the reader, their starting knowledge, their goal, and the document type from the
   request and project context.
2. Verify technical claims against current source, commands, or authoritative references.
3. Propose or infer a structure that puts the reader's next action first.
4. Write direct headings, short paragraphs, complete examples, prerequisites, expected output,
   failure recovery, and version/platform scope.
5. Test commands and links when practical. Mark unverified examples rather than presenting them
   as current fact.
6. Review terminology, navigation, accessibility, localization, and stale duplication.

## Quality bar

Every page answers: who it is for, what it helps them achieve, what they need first, how they
know it worked, and what to do when it fails. Preserve the project's established voice and
information architecture. Do not invent product capability or copy intent documents as proof of
implementation.