Docs & Code Guide

The architecture diagram nobody maintains: fix it, delete it, or change what produces it

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Almost every organisation has one. A diagram on a wiki page, exported from a tool nobody has a licence for any more, last edited by someone who left, still linked from the onboarding checklist. It is wrong in ways that are not obvious, and everyone knows it is wrong except the people using it. Leaving it alone is the most common choice and the worst one. There are three honest options, and picking between them takes about twenty minutes.

Try it free
7 min readFor anyone who inherited a diagram they did not draw

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

137/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Step one: find out whether anyone reads it

This is measurable and usually skipped. Most wikis show page views. Most repository hosts show file history. Search your chat archive for the URL. Ask in the engineering channel whether anyone has opened it this quarter, and be specific about the page rather than asking a general question about documentation.

The answer sorts the problem into three cases. Read and wrong is the urgent one, because the diagram is actively producing bad decisions. Unread and wrong is not urgent and is the easiest to resolve, because deleting an unread page costs nothing. Read and correct means someone is quietly doing the maintenance, and the useful action is to find out who and make that work visible before they get bored.

One caveat on the measurement. A diagram can have low page views and high impact, because the people who read it read it at the worst moments: the on-call engineer at three in the morning, the new joiner in week one, the security reviewer, the auditor, the vendor scoping an integration. Weight those views heavily.

Why stale is worse than missing

A missing diagram makes people ask. That is a small cost paid by someone who then gets a correct answer from a person, and the question itself surfaces which parts of the system are unclear.

A wrong diagram makes people act. They plan a migration around a queue that was removed last year, size a database for traffic that now goes somewhere else, or tell a customer that data does not leave a region when it does. The cost is not the confusion, it is the work built on top of the confusion before anyone checks.

The reason this keeps happening is structural rather than cultural. Updating a diagram that lives in a design tool, a slide deck or a wiki page sits outside the normal path of engineering work, so it is always a separate chore competing with delivery. When the effort to update exceeds the value the updater personally gets, the update does not happen, and no amount of process fixes an economics problem. See why documentation goes stale.

Deleting it properly

If nobody reads it, delete it, but do not delete it silently. Replace the page with a short dated stub: what the diagram used to describe, when it was last known to be accurate, and where the current answer lives. A dead link produces a support question, a stub answers it.

Keep the original. In a wiki that means page history, in a repository that means git history, and in both cases the file is recoverable if an audit or an incident review asks what the system looked like in a given period. Deleting the link is the goal, deleting the artefact is not.

Do the same for every copy. The reason these diagrams persist is that they were exported and pasted into a slide deck, a Notion page and an onboarding document, and killing one copy leaves the others in circulation. Search for the image filename before you declare it gone.

Rebuilding so it does not happen again

If the answer is that people do read it, redrawing it by hand only restarts the clock. The diagram has to become a function of something that already changes when the system changes, which for most teams means the repository. Connect GitHub, GitLab or Azure DevOps read only through repository sync, pick the branch or tag that represents production, and the picture is redrawn daily along with an architecture doc.

Two properties decide whether this survives contact with a real team. Node identity is derived from addresses in the source, so a re-sync updates the diagram in place instead of reshuffling it, and any node someone dragged more than twelve pixels from where the last sync left it is pinned and restored afterwards. And a sync whose structure fingerprint matches the previous run stops before generation, so the picture does not churn for a dependency bump. Without those two, automated regeneration produces a new layout every week and people stop trusting it for a different reason.

Then remove the copies. Point the README, the wiki page and the onboarding document at one live embed URL that renders the current canvas, so there is no exported image anywhere that can drift. Viewers need no account, which is what makes it viable for the non-engineering readers who were the reason copies existed in the first place.

Two years of drift, one afternoon

Generating the current picture first and then diffing it against the old one is faster than auditing the old one line by line, and it tells you what actually changed. See how to detect stale diagrams.

The diff, and the number that tells you it held

Do not audit the old diagram box by box. Generate the current one, then read the two side by side and write down three lists: nodes present in the old picture and absent from the new one, nodes present only in the new one, and edges that changed direction or disappeared. Those three lists are the real changelog of the last two years, and they take an afternoon rather than a week because you are comparing two artefacts rather than reconstructing one from the code.

Once the rebuilt diagram is running on a sync, there is a number worth watching. Each run records what share of the previous diagram survived under the same node ids, and that ratio lands in the sync log. A high ratio after a small commit means continuity is holding and the picture people learned is still the picture they see. A low ratio after a small commit is the warning that the diagram is being recomposed rather than updated, which is the failure that made the old one untrustworthy in the first place.

Two years is also long enough that some of what you find is not drift but deletion. A node with no counterpart in the new picture is either a service that was removed, in which case the finding is that nothing updated the diagram, or a service that still exists outside the connected repository, in which case the finding is that your architecture is wider than the repository you pinned. Both are worth writing down before you close the task.

Old wiki diagram (exported 2024-05)   New sync (2026-08-21, main @ 9f2c1ab)
  api                                   api
  orders                                orders
  orders-db                             orders-db
  events queue                          events queue
  reporting                             ->  gone: decommissioned Q3 2025
  -                                     ->  new: pricing
  -                                     ->  new: inventory-db
  -                                     ->  new: events consumer #2

Three findings, not a redraw:
  1 removed service nobody deleted from the picture
  2 services added since, never drawn
  1 datastore split that changed every capacity assumption downstream

FAQ

Should I delete an outdated architecture diagram?

Delete it if nobody reads it, and replace it with a short dated stub saying what it described and where the current answer is. If people do read it, deleting it removes a wrong answer but leaves the need unanswered, so the better move is to rebuild it from something that regenerates on its own.

Is a stale diagram worse than no diagram?

Yes, in most cases. A missing diagram makes people ask a question and get a correct answer. A wrong diagram makes people act on it, and the cost is all the work built on the wrong assumption before anyone checks. The readers most exposed are the ones with the least context: new joiners, on-call engineers, auditors and external partners.

How do I tell whether anyone still uses a diagram?

Check page views in the wiki, check file history in the repository, search chat archives for the URL, and ask in the engineering channel about that specific page rather than about documentation in general. Weight views from onboarding, on-call and audit contexts heavily, since those are low volume and high consequence.

Why do architecture diagrams stop being maintained?

Because updating them sits outside the normal path of engineering work. When the diagram lives in a separate tool, changing it is a separate chore competing with delivery, and the person doing the work rarely benefits from it personally. It is an economics problem rather than a discipline problem.

What stops a rebuilt diagram from going stale again?

Deriving it from something that already changes with the system, such as the repository, and removing every exported copy. A read-only connection pinned to a branch or a tag can redraw the diagram daily, and referencing that one canvas by URL from the README and the wiki means there is no second copy to drift. Watch the share of nodes that survive each sync: a small commit that recomposes the picture is the early sign of the old failure returning.