What Should an Incident Note Include for a Data Outage?
From the earlier reference collection. Read the current software blog.
Give readers a concise account of what stopped arriving, when it happened, what state the service is in, and whether published records changed.
Identify the affected source and scope
An incident note should name the data source or service component affected and describe the visible impact. Was one upstream feed unavailable, did parsing fail, or could users not reach the download endpoint? These are different failures and may affect different outputs. Avoid saying “the data is down” when only one region, product, or time range is involved.
Give a scope that a reader can act on: which files, stations, routes, or endpoints were affected, if known. If the investigation has not established the full scope, say that it is still being assessed. Do not turn an unverified suspicion into a definitive cause.
State the time span and current status
Record when the issue began and when it was detected, with a clear time zone. If the end time is unknown, label the incident ongoing. Include the last successful retrieval or update where that timestamp is available, and distinguish it from the time of the latest failed attempt.
For example, a note could say that retrievals after 14:10 UTC failed, the last successful data snapshot was at 14:05 UTC, and investigation continues. This makes clear that the page may still serve older data. Use actual recorded times in a real notice; an illustrative example should be labeled as such.
Explain published-data effects
Readers need to know whether the service displayed stale information, omitted records, or published a partial file. State what happened and what correction has been made, if any. If a previous download contained a known defect, identify the affected version or publication window and explain whether a corrected replacement is available.
Do not silently replace a file while leaving its version and publication metadata unchanged. If the service republishes corrected data, describe how users can identify it, such as a new version label or checksum. If the team cannot yet determine whether historical records were affected, say so and update the note once that review is complete.
Close with next update information
A useful incident note tells users what to do now: treat the last snapshot as delayed, avoid a specific file, or retry after an announced repair. Give a next update time only if the team can reasonably honor it; otherwise say that the notice will change when the status changes. Keep the note concise and revise the same record as facts become clearer.
After recovery, add the resolution time, the cause if established, and any lasting corrective step. Preserve the history so users can understand why data changed. A transparent outage note distinguishes service recovery from data correction and helps downstream consumers decide whether they need to rerun a process.