/writing-emdash-docs

name: writing-emdash-docs
description: Write, revise, and review EmDash documentation for technical accuracy, useful structure, house style, and natural prose. Use when working on user documentation, guides, API reference pages, migration or upgrade guides, READMEs, contributor documentation, technical specifications, or release notes in the EmDash repository, and when asked to improve, audit, de-slop, or humanize existing documentation.

Writing EmDash docs

Produce documentation that helps a specific reader complete a task or understand a concrete part of EmDash. Treat factual accuracy, information design, and sentence-level style as separate checks.

Load the right context

Load only the context needed for the artifact:

1. Read `AGENTS.md` for repository-wide rules. 2. For public documentation, read `docs/src/content/docs/contributing/docs-style-guide.mdx` completely. 3. Read [references/docs-practice.md](references/docs-practice.md) when creating or restructuring a page, changing a task path, reviewing accessibility or information architecture, or writing substantial examples. 4. Read [references/anti-slop.md](references/anti-slop.md) for prose-heavy revisions, de-slopping, or humanization. A small factual correction does not require loading it. 5. Read nearby pages of the same type to preserve established structure, terminology, frontmatter, imports, and Starlight component usage. 6. Inspect the implementation, types, tests, command help, or configuration that establishes every technical claim. Do not rely on memory when the repository can answer the question. 7. For changesets, read [.changeset/README.md](../../.changeset/README.md) completely. Treat the entry as public CHANGELOG documentation and review whether affected readers can recognize the surface, understand the observable effect, and act on any migration guidance. Frontmatter validity and technical accuracy do not make an unhelpful entry acceptable.

Define the reader and outcome

State the intended outcome privately in one sentence: "After reading this, the reader can ..." Use it to decide what belongs on the page.

Classify the document before choosing its structure:

| Document | Reader need | Default shape | | --------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Tutorial | Learn through a reliable, guided experience | Visible goal, prerequisites, one path, expected results after each stage, recap | | Task guide | Complete one practical task | Outcome, prerequisites, ordered actions, result, optional next step | | Concept or explanation | Build an accurate mental model | Definition, relevant behavior, concrete example, implications | | Reference | Look up exact behavior | Signature or syntax, parameters, defaults, return value, errors, examples | | Troubleshooting | Diagnose and resolve a known failure | Exact symptom, context, cause or diagnostic checks, workaround or resolution, verification | | Upgrade or migration guide | Make an existing project work after a change | Previous behavior, current behavior, required action, minimal diff | | README or contributor guide | Start or contribute quickly | Short purpose, fastest working path, common operations, deeper links | | Technical specification | Evaluate and implement a decision | Goal, constraints, decision, interfaces and data flow, failure handling, rollout, verification, open decisions |

Do not force every section into the same size. Give common or risky tasks more space than incidental details.

Draft for the task

• Lead with the reader's outcome. Move project history or implementation chronology to a page where it helps the reader make a decision.
• Use the words readers will search for in the title, introduction, headings, and exact error messages. Prefer specific labels to `Overview`, `Introduction`, or `Why it matters`.
• Use direct subject-verb-object sentences and precise nouns. Repeat the established name for a concept; synonyms can imply a second concept.
• Use imperative instructions for required actions. Reserve "can" for a genuine option and explain consequences when a choice matters.
• Put a condition before the action it governs so the reader knows whether the instruction applies before acting.
• Keep prerequisites explicit. Do not hide setup assumptions inside a later step.
• Prefer one realistic, working path over a menu of hypothetical choices. State the selection criteria before an opinionated example.
• Introduce code samples with what they accomplish. Add `title=` filenames to blocks that represent files.
• Keep code and output consistent with the current API. Include defaults, errors, permissions, and caveats when they affect successful use.
• Link to authoritative material for non-EmDash topics. Keep explanations focused on EmDash-specific behavior.
• Keep one canonical explanation for recurring information and link to it. Do not duplicate commands, option lists, or procedures across pages when they can drift independently.
• Preserve valid frontmatter, imports, links, anchors, code-fence metadata, and MDX component boundaries while editing prose.

For public docs, describe how to use EmDash. Put internal design detail in contributor or architecture documentation unless it changes a reader's decision.

Run the a