1. Summary
The summary is the first section of a CoE document, and should be no longer than a few paragraphs.
It should define, in as simple terms as possible, the broad scope of the error and failure that occurred. It should not define solutions, causes or actions — and it must be in a form that all stakeholders, including those not directly involved in the root-cause analysis, can understand and appreciate.
The first sentence will be read by everyone, and for many people it will be the only part of the CoE they ever read. It is worth writing it last, once the rest of the document has settled. A Summary written before the Timeline is understood will usually describe what we first thought had happened, and that is rarely what did.
Imagine a CoE that starts with the following first sentence; this can also be used as the Subject of an email:
Customers were unable to visit our site for 2 hours
(1 paragraph)
or
A customer saw another person's details and complained to a regulator
(2 paragraphs)
or
Postcode requests failed for 7 hours blocking direct debit payments
(1 paragraph)
or
Law enforcement enquiry identified pages and patterns used by terrorists
(2.5 paragraphs)
or
Customers saw the wrong price on 21 high-value items for 4 hours
(1 paragraph)
or
A robot stopped production for 9 hours
(1 paragraph)
Everyone should be able to understand the summary. Be brief and to the point and do not diagnose, describe.
The CoE Summary should not be too long. A paragraph or three is the maximum, and if the event can be summarised in a single sentence or two, that is better.
Care should be taken so that the Summary is easy to read and accessible by all — it should contain no jargon or business specific language, and as largely as possible, should avoid reference to internal systems or processes that an outsider would not easily understand.
An external entity, or a customer, should be able to read the summary and understand the context of what is being described.
A Summary usually fails in one of two ways, and they are opposites.
Our CDN began returning cached objects for authenticated routes following a change to the cache key, resulting in cross-session data exposure until rollback.
Accurate, and not a Summary. It diagnoses rather than describes, it assumes the reader knows what a cache key is, and a stakeholder who reads it still cannot tell whether anybody was harmed.
There was a brief issue affecting some customers, which has now been resolved.
This describes rather than diagnoses, which is right, and it says nothing at all. A reader cannot tell what happened, to how many people, or why we are writing a document about it.
For 38 minutes on the evening of 2 March, some customers who signed in were shown another customer's account page. We rolled the change back, told the Information Commissioner and wrote to everybody affected.
Both faults are avoided in the same way: describe what a customer experienced, and what we did about it, in the order that somebody outside the team would ask.
Explain it like I am five. Everyone should be able to understand this section, and if need be, go no further.