Documentation & Review — Skills

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 <name>. 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 <name>

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 — <decision>, and name the decision that would unblock it.
Partial material — produce every section the material supports, mark the rest INCOMPLETE — pending <question>, and deliver. A short verified document beats a complete-looking one that filled its gaps.

Download .md

README & Onboarding Guide

Produces the document a new contributor reads first — and can work from without asking a question the document should have answered.

Deliverable

One Markdown document, readme.md, in the structure set out under Output below. It is the entry point the rest of a project's documentation is reached from, and an input to Documentation Audit.

Required inputs

Repository access — the tree itself, including the build, dependency and configuration files.
A machine the setup can be run on — every step in this document is executed before it is written down.
Who this is for — someone new to the team, someone contributing from outside, or someone returning after a long absence; they need different things.

Without repository access, stop and report it. Without a machine to run the setup on the guide can still be written, but every step is marked unverified and the document says so at the top.

Optional inputs

The maintainers, and where they answer questions
The review and contribution process, and the branch rules that go with it
An existing onboarding document, and the questions it failed to answer
The supported operating systems and the differences between them
The accounts, credentials or access a contributor must request before starting
Known setup failures and what they turn out to be

An absent optional input becomes a named gap in section 9, not a plausible sentence. A guide that guesses at the access a contributor needs sends them to the wrong person.

Execution

1 — State what this is and what it is not. Two or three sentences: what the project does, who uses it, and the neighbouring things it is not. A contributor who has misunderstood the purpose will misread every instruction that follows.

2 — Take the prerequisites from the project, not from habit. Read the dependency, build and configuration files and take the required versions from them. Where a version is pinned, write the pin. Where a range is allowed, write the range. A version taken from what happens to be installed on one machine is a guess with a number on it.

3 — Run the setup on a clean checkout and write down what you did. Every command in the order it was run, including the ones that were needed and documented nowhere. If a step required access you already had, say so — it is a prerequisite the contributor does not have yet.

4 — Run it, then test it. Record the command that starts the project, what the reader should see when it worked, the command that runs the tests, and what a passing run looks like. A contributor who cannot tell success from silence will carry on and break something further along.

5 — Map the tree. The directories a contributor will touch, what lives in each, and where a new thing of each kind goes. Skip the parts nobody edits by hand; here they are noise.

6 — Write the conventions a contributor would be corrected on. Commit message shape, branch naming, formatting, the review a change must pass, and anything the project rejects automatically. An unwritten convention is a rule the newcomer finds out about in review.

7 — Name where to ask. The place questions go, who answers them, and what to include in the question. Then mark unverified every step you could not execute.

Output

readme.md, in this order:

1. What this is — purpose, who uses it, and what it is not
2. Prerequisites — per requirement: what, the version the project requires, and the file that version was read from
3. Access and accounts — what must be requested before starting, and from whom
4. Setup — numbered commands, each with its expected result and whether it was executed
5. Running it — the command, the expected output, and the common first failure
6. Testing — the command, what a passing run looks like, and what to do with a failing one
7. Project layout — directory, what lives there, and where new work of that kind goes
8. Conventions — the rules a change is reviewed against
9. Where to ask and what is missing — who answers, and every step marked unverified

Validation

The document is ready when all of these hold:

Every command in sections 4 to 6 was executed, or is marked unverified
Every version in section 2 cites the project file it was read from
Section 4 starts from a clean checkout and assumes no prior state
Sections 5 and 6 each state what success looks like
Section 1 says what the project is not, in at least one sentence
No tool, service or account is named without telling the contributor how to obtain it

Fail the run if a version appears that was not read from a project file, or if a documented command was never executed and is not marked unverified.

Failure handling

No repository access — stop. Report that onboarding cannot be written from a description of a project.
The setup cannot be completed — document up to the step that failed, record the failure and its exact message, mark the remaining steps unverified, and list the blocker in section 9. Do not write the steps you expect would follow.
Undocumented manual steps — record them as steps with their own numbers, not as a note in the margin. The step someone does from memory is the step a newcomer never finds.
Prerequisites contradict each other across files — record each version with the file it came from, mark the point disputed, and raise it in section 9 as blocking.
No named contact — write unknown in section 9 and state that a contributor has nowhere to ask. A guide that ends with no route to a person stops working the first time it is wrong.

Download .md

Runbook Authoring

Produces the procedure someone follows under pressure, at night, with no context and no author to ask.

Deliverable

One Markdown document, runbook.md, in the structure set out under Output below. One runbook covers one procedure; a second procedure gets a second document.

Required inputs

The procedure — the operation to be written down, and the condition that starts it.
The system it runs against — access to it, or to someone who will execute the steps while you record them.
Who will run it — the role, and what that role is permitted to do without asking.

If any of the three is absent, stop and report which one. A runbook written without knowing who runs it either assumes access they do not have or withholds steps they need.

Optional inputs

Previous incidents where this procedure was used, and what went wrong
The monitoring, alerts or symptoms that indicate this runbook applies
The change and approval process this operation must respect
A non-production environment the steps can be rehearsed in
The escalation structure, by role
The audit or compliance record this operation must leave behind

Where an optional input is absent, the runbook says so at the point it matters: an unrehearsed step is marked untested, an unknown escalation route is written unknown in section 7. It is never filled in with what is likely.

Execution

1 — Fix the boundary. When this runbook applies and — just as important — when it does not, naming the nearest procedure for the cases it does not cover. An operator confidently following the wrong runbook does more damage than one who stops.

2 — List the preconditions and the access. What must be true before the first step, and what permissions, credentials or approvals the operator needs in hand already. Anything that would have to be requested mid-procedure is a precondition, not a step.

3 — Write the steps, each with its verification. One action per step, in order, with the command or control named exactly and the variable parts written as <name>. Under each one, how the operator confirms it worked. A step with no verification is a step whose failure is discovered later, by something else.

4 — Write the decision points as branches. Where the procedure forks, state the observable condition and what to do on each side. No step may say as appropriate: under pressure that phrase means the operator is guessing, and the runbook has handed the decision back to the person least able to make it.

5 — Write the rollback. For every step that changes state, how to undo it and whether it can be undone at all. A step that cannot be reversed is marked IRREVERSIBLE and carries its own confirmation before it runs.

6 — Handle failure in place. Under each step, what to do when it fails, rather than one section at the end. Then the escalation: who to involve, by role and not by name, at what point, and what to tell them.

7 — Rehearse, then mark what was not rehearsed. Execute the procedure where it is safe to, correct what the run reveals, and mark untested every step you could not execute. Record what must be captured afterwards: times, decisions taken, and the state the system was left in.

Output

runbook.md, in this order:

1. Scope — when this applies, when it does not, and where to go instead
2. Preconditions — what must be true, and the access the operator needs
3. Roles — who runs this, and who must be told that it is running
4. Steps — numbered, one action each, with the verification and the failure response beneath
5. Decision points — the observable condition, and the branch taken in each case
6. Rollback — per state-changing step: how to undo it, or IRREVERSIBLE
7. Escalation — the trigger, the role to contact, and what to hand them
8. After the run — what to record, where, and who reviews it
9. Rehearsal status — which steps were executed, which are untested, and when this was last run

Validation

The runbook is ready when all of these hold:

Every step in section 4 states one action and how to verify it
No step contains as appropriate, if needed or any other instruction that returns the decision to the operator
Every state-changing step appears in section 6, with its rollback or as IRREVERSIBLE
Every branch in section 5 names an observable condition, not a judgement
Section 7 names roles, never individuals
Every step not executed during rehearsal is marked untested in section 9

Fail the run if a step changes state with no entry in section 6, or if any step was written without being executed and without being marked untested.

Failure handling

No access to the system — write the procedure from the supplied material, mark every step untested, and state at the top that this runbook has never been executed. Say plainly that it must be rehearsed before it is relied on.
A step cannot be rehearsed safely — mark it untested with the reason, and write the verification the operator should expect from the step's definition rather than from a run.
The procedure has no rollback — say so in section 6 rather than leaving it empty, mark the step IRREVERSIBLE, and add the confirmation the operator must make before it.
No escalation structure supplied — write unknown in section 7 and list it as blocking. A runbook that ends on a failed step with no route onward leaves the operator stranded.
Conflicting accounts of the procedure — record each version with its source, mark the point disputed, and do not merge them into one sequence. A merged procedure nobody has run is worse than two that someone has.

Download .md

Release Notes & Changelog

Turns a set of merged changes into what a reader needs: an entry for the record, and notes for the person the change happens to.

Deliverable

One Markdown document, release-notes.md, in the structure set out under Output below. It carries both forms: section 2 is the entry appended to the project's changelog, and section 4 onward is what is published to readers.

Required inputs

The set of merged changes — the commits, merges or tickets included in this release, and the boundary they sit inside.
The version identifier — what this release is called, supplied by whoever names releases here. It is never invented.
The reader — who the notes are published to: the people running the software, the people integrating against it, or both.

If the change set or the version identifier is missing, stop and report it. Notes assembled from a memory of what was worked on will omit exactly the change that breaks someone.

Optional inputs

The tickets or issues the changes close, and what they said
The previous release's notes, for continuity of terminology
Migration steps already written by the people who made the change
Deprecation decisions and the date a removal is planned for
Measurements taken before and after a performance change
The channel the notes are published to, and the length limits it imposes

Absent optional inputs reduce what the notes may claim. Without measurements a change is described but never called faster; without a removal date a deprecation is recorded as planned with unknown beside it.

Execution

1 — Take the change set from the record, not from recollection. List every merged change inside the boundary. Each entry in the output traces to one of them, and a change that reaches the output with nothing behind it is removed.

2 — Sort by what it is. Added, changed, fixed, removed, security. Sort by effect on the reader rather than by the component that was touched: a reader looks for what happened to them, not for which module it happened in.

3 — Separate visible from internal. A change the reader can observe goes in the notes. A refactor, a test or a build change is recorded as internal and stays out of the reader's section. Dressing an internal change as a user-facing improvement is how release notes lose their readers.

4 — Pull the breaking changes to the front. Anything that stops working, changes shape or requires action goes at the top, with the action spelt out. A migration step buried under a feature list is a migration step that will be missed.

5 — Write each entry as its effect. State what is different for the reader and what they do about it, not which function was edited. Where an entry has a ticket or a change behind it, cite it so a reader can go further.

6 — Claim only what was measured. A change may be called faster, smaller or more reliable only with a measurement behind it. Without one, describe what changed and leave the judgement to the reader.

7 — Record the deprecations and what is next. What is deprecated, what replaces it, and when it will be removed — unknown where no date has been decided. Then check every entry against the change set one last time.

Output

release-notes.md, in this order:

1. Release identity — the version identifier as supplied, the date, and the boundary of the change set
2. Changelog entry — grouped Added, Changed, Fixed, Removed, Security; one line per change, each citing what it came from
3. Internal changes — changes with no reader-visible effect, recorded and kept out of section 4
4. Breaking changes and required action — what stops working, and the exact steps to take; empty only if there are none, and it says so
5. What is new — per entry: the effect on the reader, and what they can now do
6. Fixes — the symptom the reader would have seen, and that it is gone
7. Deprecations — what is deprecated, its replacement, and the removal date or unknown
8. Unverified claims — anything asserted with no measurement or traceable change, listed rather than published

Validation

The document is ready when all of these hold:

Every entry in sections 2 and 4 to 7 traces to a change in the input set
Every change in the input set appears once, in section 2 or section 3
Section 4 comes before section 5 and states its steps as actions the reader takes
No entry claims a measurable improvement with no supplied measurement
The identifier in section 1 is the one that was supplied, unchanged
Section 3 is used for internal work rather than leaving it out

Fail the run if an output entry traces to no change in the input set, or if an improvement is claimed with no measurement behind it.

Failure handling

No change set supplied — stop. Report that release notes cannot be reconstructed from what people remember doing.
No version identifier — produce the document with section 1 marked VERSION NOT ASSIGNED and name who assigns it. Do not invent an identifier and do not increment the previous one.
A change's effect on the reader is unclear — list it in section 8 with the question and ask the person who made it. Do not describe it vaguely to fill a line.
A breaking change with no migration path — record it in section 4, state plainly that no migration is available, and raise it as blocking the release. A breaking change with no path is a decision, not a note.
Partial change set — produce the document for the range that is known, state the boundary in section 1, and mark it INCOMPLETE — covers <range> only.

Download .md

Documentation Audit

Reads a documentation set against the system it describes and reports every place the two disagree.

Deliverable

One Markdown document, documentation-audit.md, in the structure set out under Output below. Its findings are the input to Technical Documentation Authoring and to the correction of each document it names.

Required inputs

The documentation set — the documents in scope, and where each one lives.
The system they describe — read access to the code, configuration and interfaces the documents make claims about.
The reader the set is meant to serve — the audit reports what is missing, and missing is only meaningful against a reader.

Without both the documents and the system, stop and report which is missing. Documentation cannot be audited against itself; a set can be internally consistent and wrong throughout.

Optional inputs

An environment where the documented commands can be executed
The history of the system, to tell a removed behaviour from one that never existed
The support questions readers actually ask
The owner of each document, so findings have somewhere to go
Previous audits, and which of their findings were accepted
The release the documents are supposed to be current as of

Without an environment, examples are checked by reading rather than by running, and every such finding is marked checked by reading so nobody treats it as proven. Absent owners are recorded as unknown rather than assigned.

Execution

1 — Inventory the set. Every document in scope: where it lives, what it claims to cover, who owns it, and when it last changed. A document nobody named is still read by somebody, so walk the tree rather than working from the list you were handed.

2 — Extract the checkable claims. From each document, every statement the system can confirm or contradict: commands, paths, parameters, option names, defaults, sequences and stated behaviours. Opinions and rationale are not checkable and are not audited here.

3 — Check each claim against the system. For every claim, find the code or configuration that settles it. Record the document location and the system location together; a finding that cites only the document is an assertion, and the document's author will treat it as one.

4 — Run what can be run. Execute the documented commands and examples in a safe environment and record what happened. Where nothing can be executed, mark the finding checked by reading and say so in the report rather than in a footnote.

5 — Classify what you found. A statement contradicted by the system, a command or path that no longer exists, an example that would fail, behaviour that was removed and is still documented, and behaviour that exists and is documented nowhere. Each is a different repair, so each gets its own list.

6 — Find what is missing for the reader. Walk the task the reader is meant to complete and mark every point where they would have to guess, read the code, or ask someone. An undocumented step is a finding even when everything written is correct.

7 — Order by the cost of believing it. Rank findings by what happens to a reader who trusts the wrong statement — data lost, access granted, time wasted — and not by how easy the fix is. Then record what was left uncovered.

Output

documentation-audit.md, in this order:

1. Scope and date — the documents audited, the system state they were checked against, and when
2. Method — what was executed, what was checked by reading, and what was not checked at all
3. Contradicted statements — per finding: the document location, the claim, the system location, and what is actually true
4. Broken procedures — commands, paths or steps that no longer exist, each with its document location
5. Failing examples — the example, where it is, and what happened when it was run or why it would fail
6. Removed behaviour still documented — what is described, and the evidence that it is gone
7. Undocumented behaviour — what exists, where, and which reader needs it
8. Gaps for the reader — the point in the task where the reader would have to guess, and what they need
9. Findings by cost — every finding ordered by the consequence of believing it, with an owner or unknown
10. Not covered — documents or claims the audit could not check, and why

Validation

The report is ready when all of these hold:

Every finding in sections 3 to 7 cites a document location and a system location
Every finding is marked as executed or as checked by reading
Section 9 contains every finding from sections 3 to 8, ordered by consequence
No finding proposes a rewrite without naming the statement that is wrong
Section 10 is either non-empty or states explicitly that the whole set was checked
No claim about the system appears that was not read from the system

Fail the run if a finding cites a document without citing the system location that contradicts it, or if a severity is assigned without stating the consequence behind it.

Failure handling

No access to the system — stop. Report that an audit without the system compares documents with each other, which is proofreading and not an audit.
No environment to run in — audit by reading, mark every finding checked by reading, and state in section 2 that nothing was executed.
The system is mid-change — audit against a named state, record that state in section 1, and mark pending <change> the findings the in-flight change would resolve.
A document has no owner — record unknown in section 9 and list it in section 10. An unowned document accumulates findings and none of them get fixed.
The set is too large to cover — audit the documents on the reader's main task first, state the boundary in section 1, list the rest in section 10 as uncovered, and mark the report PARTIAL.

Download .md