Writing up an incident

This guide is for the person responsible for investigating and writing up the incident. This will not necessarily be the incident lead who responded to the incident.

Most incidents get a report, based on this template, with:

• An overview of the incident, including impact figures

  • requests/visits/users impacted and over what time
• A timeline of events and response actions
• An explanation of the incident, including contributing factors
• Any proposed actions

This is primarily an internal document, but a condensed version will be made available to the client. You should store it in a new folder in the incidents folder on Drive along with all files relating to the incident.

First draft #

You should prepare a draft report immediately after the incident, and should focus on the objective data like Slack transcripts, screenshots, and logs. Subjective data like opinions, judgments, assumptions, and beliefs will come up in the review meeting. You should avoid using names to avoid appearing to blame people.

You should circulate the draft to those involved in the incident in advance of the incident review meeting, and any minor amendments should be done as comments/suggestions in the doc. Anything that requires discussion should wait until the incident review. Getting comments in advance helps us make the best use of the meeting time.

‘Draft’ in this case means that all sections should be completed in at least outline form, but there may be some outstanding questions that need answering and some additional detail that is needed. Part of the purpose of the incident review is to fill in these gaps.

Final version #

You should produce a final version of the report with more detail following the review meeting (see below).

An abridged version with a link to the full report should be published internally on Bikeshed, and copy should be shared with the affected clients (usually through a Zendesk ticket). You should check the client version by a director for anything that might make us commercially liable, but as a rule we should be as open as possible.

Last updated: 2 January 2025 (history)