A finished incident write-up is one of the densest teaching documents in engineering. In a few pages it holds a timeline, a technical explanation, a judgement about causes and a list of changes. Most readers skim it for the headline. A more productive method is to dismantle it in a fixed order, asking of each section how it was built and what its author chose to include or leave out. This guide gives that method as six steps, and it uses one concrete example: an imagined write-up about a product page that slowed to a crawl after a cache setting expired for every item at the same moment.
The aim is to borrow the structure of a well-made incident write-up for your own documents, never the content of someone else’s failure.
Step 1: read the summary, then predict the rest
Start with only the first paragraph. In our example it says that the product pages were slow for about an hour, that the cause was a synchronised cache expiry, and that a staggered expiry was introduced afterwards. Now close the document and write down what you expect the remaining sections to contain. This takes two minutes and sharpens your attention, because every later difference between your prediction and the real text is information about the author’s priorities.
Step 2: rebuild the timeline on paper
Find the timeline and redraw it as a single horizontal line. Mark four points: when the problem began, when someone noticed, when the first action was taken, and when normal service returned. The gaps between points are where the reading gets interesting. A long gap between start and notice says something about detection; a long gap between notice and action says something about decision-making. A good write-up lets you measure those gaps without arithmetic.
Pay attention to how times are written. Consistent time zones and a fixed format are small signs of care, and they are easy to copy.
Step 3: separate what was seen from what was concluded
Underline observations in one colour and conclusions in another. An observation says that response times rose and that the cache hit rate dropped. A conclusion says that a simultaneous expiry caused the drop. Strong write-ups keep these apart, so a reader can disagree with the conclusion while still trusting the observations. If the two are tangled, note it as a structural weakness and consider how you would untangle them.
For readers who want a broader frame on handling uncertainty in delivery work, an article on weighing risk when you ship software makes a useful companion to this step.
Step 4: look at how causes are framed
Our example lists three contributing factors, not a single culprit: a default expiry applied to every item, a lack of any random spread in expiry times, and a load test that had never simulated a cold cache. Notice the grammar. Each factor describes a condition in the system, not a failing of a person. That framing is deliberate and it makes the document safe to share widely.
When you take apart your own organisation’s write-ups, check the verbs. Phrases about systems invite fixes; phrases about individuals invite silence next time. The cultural side of that choice is discussed in a guide to managing cultural change in delivery teams.
As a small exercise at this stage, take the example’s three factors and try to write one sentence for each that contains no person, only a condition of the system. “The expiry value was identical for every item” works. “Someone forgot to randomise” does not. Doing this a few times trains the ear, and soon you can hear when a draft has slipped toward blame.
Step 5: examine the action list
The final section of the example lists four actions. Look at their shape, not their content. Each has an owner described by role, a target description of done, and a note on how the team will know the action worked. One of them is explicitly marked as deferred, with a reason. Deferred items stated openly are a sign of a mature document; it would be more worrying if every action were claimed as complete.
Count how many actions change the system and how many change a process. A healthy list usually contains both. If every action is “add more monitoring”, the write-up may be treating symptoms.
One further observation about the example: its writer included a short paragraph titled “what went well”. Quick detection by a customer-support colleague, a fast rollback of the configuration and clear communication in the incident channel all earned a line. That section is easy to overlook and valuable to copy, because it records the habits worth keeping, which are otherwise invisible once the incident ends.
Finally, look at length. The whole document fits on three pages, with the timeline taking less than a third of the space. Brevity here is a structural decision. The author trusted the reader to follow a short account and provided links to raw graphs and logs for anyone who wants depth.
Step 6: write the skeleton and test it on something small
Finally, extract the structure as a blank template with headings only: summary, timeline, what was observed, contributing factors, actions with owners, open questions. Try it on a minor event from the last month, such as a failed deployment that was fixed in ten minutes. If the skeleton handles a small event gracefully, it will handle a large one.
The habit also extends beyond documents and into any page that has to sort a lot of material. One more place to practise: the home page of a digital product and engineering company shows tabs for solutions, services and training, and, in its own wording, a blog and stories area as well. Reading how a menu is ordered tells you what the organisation wants a newcomer to meet first. Documents work the same way.
Mistakes to avoid while you work
- Reading for blame. The point is structure, so if you find yourself judging people, return to step three.
- Copying phrases. Borrow headings and order, and write your own sentences from your own facts.
- Treating one write-up as the standard. Read at least three from different teams before settling on a template.
- Skipping the open questions. That section, when present, tells you what the authors honestly did not know.
What you take away
After one pass you should have a prediction log, a redrawn timeline, a two-colour marked document, a note on how causes were framed, an annotated action list and a reusable skeleton. That is six artefacts from a single afternoon, and together they change how you write and how you read. The next time an incident happens on your own watch, you will already know what a good account of it looks like.









