---
alwaysApply: false
globs: ["**/*"]
description: "Documentation for whoever runs the product: routine change, recovery, fault reports, contacts. Use when a non-developer will operate it."
---

# Operator Documentation

**Produce one document for the person who runs the product.** They may never
have written code. They know the business, not the system. Keep it separate
from the developer documentation and never link into it. It answers four
questions, in this order, each as a numbered task:

- How do I make a routine change? Name the changes the operator makes often —
  closing a week, changing an opening time, correcting a price — and give the
  steps for each, with what they see after each step.
- How do I get back to the last working state? One named path, the same one
  the release record rehearses, written as steps the operator can run alone.
- What do I do when a user reports a fault? What to ask the user, what to
  write down, which code to ask them to read out, and what to try first.
- Who do I contact? A name, how to reach them, when they answer, and what to
  send. Add one fallback for when that person does not answer.

**Write it in the operator's language.** Their words for their things. No
skill names, no file paths they never open, no component names. Where a
technical word cannot be avoided, define it once in the sentence that first
uses it.

**Show the state the operator can see.** For every task, state what the screen
shows when it worked and what it shows when it did not. An operator with no
success signal cannot tell a finished task from a stuck one.

**Keep the document current from the incidents.** After every incident, add or
correct one task in this document, and say which incident taught it.

**Measure readability before you publish.** The shipped readability targets
are the acceptance criterion for this document, in the language the operator
reads. A document that misses them is not finished, so split sentences,
replace rare words, then cut filler, and measure again.

**A reviewer checks:**

- all four questions are answered, each as numbered steps with a visible
  result;
- the measured readability meets the shipped targets, and the measurement is
  recorded with its date;
- the contact entry names a person, a channel, answering hours and a fallback;
- no step needs a terminal, a code editor or a credential the operator lacks,
  unless the document says who to ask instead;
- an operator who has not seen the system performs one routine change from the
  document without help `[ASSUMPTION]`;
- the last incident produced a change in this document.