# Technical Documentation Authoring Produces a document written for a named reader and a named task — with every statement checked against the system rather than recalled. ## Deliverable One Markdown document, `technical-document.md`, in the structure set out under **Output** below. It is the input to **Documentation Audit** whenever the system it describes changes. ## Required inputs - **The subject** — the system, component or procedure to be documented, with access to it or to the material that describes it. - **The reader** — who the document is for, and the knowledge they already have. - **The task** — what that reader must be able to do once they have finished reading. If any of the three is absent, stop and report which one. A document written without a named reader and a named task is written for nobody, and it shows. ## Optional inputs - Repository access, schemas, interface definitions, configuration files - An existing document on the same subject, and what is wrong with it - The publishing location and the format it imposes - A terminology list or house style the document must follow - A reviewer who can confirm the technical statements - The support questions the document is meant to make go away Every absent optional input narrows what can be verified, not what is claimed. Where one is missing, the affected statements are marked `unverified` and listed under **Open questions**. ## Execution **1 — Decide the document type.** An explanation, a how-to, a reference and a tutorial answer different questions and are read in different states. Pick one and write its name at the top. Mixing them is the most common reason documentation fails: a reader who needs a command is made to read a rationale, and a reader who needs the rationale is handed a command. **2 — Name the starting knowledge.** Write down what the reader is assumed to know before the first line, and what they are not. An assumption left silent is a reader stuck at step one with no way to tell whether the document or their own setup is wrong. **3 — Gather and verify the facts.** Take every statement from the code, the configuration or the running system — not from memory and not from an earlier document. Record where each one was checked. A statement that could not be checked against anything is marked `unverified` in the draft; it is never stated flat. **4 — Draft to the shape of the chosen type.** A how-to is an ordered sequence to one outcome. A reference is exhaustive and looked up rather than read. An explanation gives reasons and trade-offs. A tutorial is a rehearsed path that works end to end for a beginner. Write what the chosen type requires and leave the rest to other documents. **5 — Make every instruction executable.** Each command, path, parameter and file name appears exactly as it must be typed, with the variable parts written as ``. Every step says what the reader should see when it worked, so a failure is caught where it happens rather than three steps later. **6 — Cut what the reader does not need.** Remove the history, the apology and the rationale that belongs in an explanation. Length is not the measure — a reader who has to skim to reach the instruction will skim past it. **7 — Collect what could not be verified.** Every unverified statement, every question the material could not answer, and who can settle it. ## Output `technical-document.md`, in this order: - **1. Title and type** — the subject, and which of the four types this document is - **2. Reader and task** — who this is for, and what they can do after reading it - **3. Assumed knowledge** — what the reader must already know, and what is out of scope - **4. Body** — the sections the chosen type requires, in the order the reader needs them - **5. Verification notes** — per group of statements: where it was checked, or `unverified` - **6. Related documents** — what to read before this one, and what to read next - **7. Open questions** — what could not be verified, and who can settle it ## Validation The document is ready when all of these hold: - Section 1 names exactly one document type, and the body keeps to it - Section 2 names a reader and a task, not a subject area - Every command, path and parameter in section 4 was taken from the system, not recalled - Every step in a procedure states how the reader knows it worked - Every statement that could not be checked is marked `unverified` in section 5 - No placeholder in the body is left as example content; placeholders read `` Fail the run if the body mixes two document types, or if any statement is presented as fact with no verification entry behind it. ## Failure handling - **No reader or task supplied** — stop. Report which is missing. Do not choose a reader: a guessed reader produces a document that fits nobody. - **No access to the system** — write from the supplied material only, mark every statement `unverified` in section 5, and state at the top that nothing was checked against a running system. - **Sources contradict each other** — record both statements with both sources, mark the point `disputed`, and raise it in section 7. Do not settle it by taking the more recent one. - **The subject is still changing** — document the part that is settled, mark the rest `pending — `, and name the decision that would unblock it. - **Partial material** — produce every section the material supports, mark the rest `INCOMPLETE — pending `, and deliver. A short verified document beats a complete-looking one that filled its gaps.