Make architecture diagram updates part of the Definition of Done

Architecture documentation is often assigned after implementation, when everyone is already moving to the next priority. That is why "update the diagram later" usually means "never."

Direct answer: Add diagram updates to the Definition of Done only for changes that alter architecture-relevant facts. Define those facts explicitly, make the update part of the same work item, and require a reviewer to confirm the current diagram. Do not require documentation changes for routine code that leaves boundaries and behavior unchanged.

Define what counts as architecture-relevant

A diagram update should be considered when a change affects:

• service or team ownership;
• component boundaries;
• synchronous or asynchronous communication;
• data stores or data movement;
• external systems;
• security or trust boundaries;
• failure handling, retries, or queues;
• deployment topology at the documented level.

This list prevents both neglect and unnecessary bureaucracy.

Put the work in the estimate

If the diagram is required, updating it is part of implementation, not volunteer labor. Include the task in planning and review. The update may take minutes when the source is maintainable, but it still needs explicit capacity.

Teams resist documentation requirements when they are hidden work. Make the cost visible.

Update the diagram before final review

The best moment is after the design is accepted and before the ticket closes. Reviewers can compare the proposed system behavior with the updated diagram while the change is still fresh.

For large changes, create the diagram version during design review and confirm it after implementation. For smaller architecture changes, update it in the same review cycle.

Keep history additive

Do not silently replace the old artifact. A new version should record what changed and why. This helps incident reviews and prevents the team from confusing implementation drift with deliberate evolution.

Avoid the universal checkbox

A blanket "docs updated" checkbox quickly becomes meaningless. Ask a specific question: "Does this change alter anything represented in our current architecture map or critical-flow diagrams?" If yes, name the affected artifact and version.

Specificity creates accountability without forcing busywork.

Where Arialine fits

Arialine can make the documentation step conversational. A reviewer can request "add the DLQ after three retries" in the Slack design thread, and the accepted update becomes a new diagram version with source-message provenance.

That reduces the distance between the design discussion and the documentation task.

FAQ

Should every pull request update a diagram?

No. Only changes that alter facts represented by an authoritative diagram should trigger an update.

Who verifies the diagram?

The same technical reviewers who understand the change, ideally including the artifact owner or affected team.

What if implementation differs from the approved diagram?

Update the diagram and record the reason before completion. The mismatch may reveal an unreviewed architecture decision.