The service map is reviewed every quarter. Two days after a review, a team moves retries from the API to a worker. Should the map wait three months? No: its update trigger was the changed flow, not the next calendar reminder. Review dates are a safety net for changes people missed. Give each diagram a stated question and owner, update it when an answer changes, and use periodic review to test whether it still describes the system. The C4 diagram checklist also treats a diagram as a communication tool with a particular audience and scope; a view with no remaining use may be better archived than repeatedly “refreshed.”
Direct answer: Update a diagram whenever a change alters something it shows. Review active top-level diagrams about once a quarter as a safety net, and also after major incidents, reorganizations, and onboarding feedback. If a diagram keeps drifting, simplify it to a level the team can maintain. Archive it if it explains past decisions, or delete it if it has no remaining value.
Event-driven updates come first
Update when the system changes at the diagram's level of detail:
| Diagram | Update when… |
|---|---|
| System context | Users, external systems, or trust boundaries change |
| Container | Services, data stores, or major communication paths change |
| Critical flow | Steps, failure handling, or ownership in that flow change |
| Deployment | The documented topology changes |
Internal refactors that do not change what the diagram shows should not force cosmetic edits. The practical way to make this happen is to tie it to work: see architecture diagrams in your Definition of Done.
Three moments that expose drift
- Milestones. Before a large release or migration, confirm the intended state. After it, record the actual state, including compromises made during implementation.
- Incidents. If responders discovered a dependency, retry path, or owner the diagram did not show, updating it is part of the follow-up. A diagram that never improves after incidents is ignoring its best feedback.
- Onboarding. New hires notice missing labels and unexplained components. Their questions are a free review. The new-hire documentation test turns this into a routine.
The periodic review is a safety net
For active, authoritative diagrams, a quarterly review is a reasonable default. Fast-moving teams may prefer monthly, and stable systems twice a year. The review should confirm:
- the owner and status (current, historical, or draft);
- the scope: does it still answer the question it was made for?
- whether anyone still uses it;
- that the content matches the system, not just that it was "looked at".
Never update a "last reviewed" date without checking the content. A fresh date on a wrong diagram is worse than an honest old one.
Update, archive, delete, or simplify
Not every stale diagram should be fixed. Use this decision table:
| If the diagram… | Then… |
|---|---|
| Serves an active audience and its scope is maintainable | Update it, and confirm the owner and trigger so it does not drift again |
| Explains a past decision or system state | Archive it with a banner: period covered, status, and link to what replaced it |
| Duplicates a better source, is an orphaned draft, or would mislead even with a label | Delete it, following your retention and compliance rules |
| Keeps drifting because it shows too much detail | Simplify it: keep boundaries and major flows, let code and generated docs hold the rest |
Simplifying is often the most valuable option, because it reduces all future maintenance. Questions that make the choice obvious: Who uses it? What decision does it support? Is another source more authoritative? Can we really maintain this level of detail? What harm does a wrong reading cause?
Do not run a one-time cleanup without changing the process that caused the decay. Otherwise you will do it again next year.
Set a trigger from the diagram's promise
An incident-response map promises to show who receives alerts and which service owns escalation. When an ownership rotation changes, update the map at the same time, because a wrong answer could delay a response. A high-level product context map may remain valid through several internal refactors. Give each view its own trigger and maximum review interval instead of imposing one calendar date on every diagram.
When owners discuss these changes in Slack, update the current Arialine view: an addressed correction can become the next version with its reason attached. During a review, ask an owner to trace one real change since the last check. If the diagram missed it, fix the view and the trigger that failed. If nothing relevant changed, record what was checked rather than silently refreshing the date. The C4 checklist is a useful reminder to judge whether the diagram still communicates the right story at the right level.
Where Arialine fits
Arialine makes the event-driven layer cheaper when the triggering event is a Slack message. The reply that accepts a change can ask the board for it, and the change becomes the next version, linked to that message. The quarterly review then only needs to catch missed drift, not redraw everything.
To retire a board, rename or label a retired board as superseded and point to its replacement in the thread. The owner can also mark a board stale, which turns its status dot red. Its full version history stays with the board.
Derive the cadence from change risk
The C4 review checklist focuses on whether a diagram communicates its intended story, scope and relationships. Use that review after changes that affect boundaries, dependencies, data flow, trust or ownership. A calendar review is only the safety net for changes the event triggers missed.
Set shorter intervals for diagrams used during incidents, security reviews or onboarding; use longer intervals for stable context maps. Record the last evidence checked, not merely the date someone opened the page. If repeated reviews find no decision-relevant change, simplify the view or lengthen the interval.
Next step: classify each maintained diagram by consequence of being wrong, then assign an event trigger and maximum review interval.
FAQ
Is a quarterly review enough by itself?
No. It is a fallback. A critical diagram should change when the system changes.
Should every diagram show a last-reviewed date?
Yes, along with its owner and status. Version history is better still, because it shows what changed and why.
Is deleting documentation dangerous?
Keeping misleading documentation is dangerous too. Follow your retention policy, preserve meaningful history by archiving it, and remove noise deliberately.
Sources
- C4 model: Diagram review checklist — reviewed September 27, 2026
- Google Engineering Practices: Documentation in review — reviewed September 27, 2026
Add to my Slack