Technical Document Authoring

Use this capability whenever you write or review a technical document in the software or web engineering domain — a design doc, an RFC, an ADR, a runbook, a README, or an API reference. It runs in two modes over the same set of rules:

• Author — draft and restructure the document so its reader reaches the answer without rereading. Choose the shape that is clear by construction — the reader named before the first sentence, one document type, the takeaway at the top — rather than the shape you patch on a later pass.
• Review — read a draft for what it will cost its reader, and raise each problem as a finding against a specific passage. Hold the line the same way in both modes; the standard does not soften because you wrote the draft yourself.

Scope is the writing craft of documents whose readers are a team — engineers, reviewers, operators, and whoever inherits the system. The audience assumptions, vocabulary, and example forms (code blocks, terminal sessions, API shapes) reflect that. Out of scope: published and personal writing such as blog posts, talks, and newsletters; marketing copy; fiction; academic papers outside software; and end-user documentation for non-software products.

This capability is the owner of plain-English and vocabulary-level discipline for documents (see voice-tone-and-maintenance.md). Where a neighbouring capability owns a rule instead, this one names it by topic rather than restating its wording. Those deferrals are conditional — skip one cleanly on a project that ships no such capability, and apply the rules here in its place:

• A product-requirement or specification capability owns a spec's section skeleton, requirement phrasing, and acceptance criteria. This capability owns the sentences inside whatever structure that one prescribes.
• An agent-skill authoring capability owns the prose inside a skill definition and its reference files, adding skill-format rules on top of these.
• A conversational-reporting capability owns the chat turn, the progress note, and the completion summary — the reply, not the document.
• A UI or visual-design capability owns the accessibility of an interface. This capability owns the accessibility of a document.

Guidelines: