Your Architecture Repository Has an Audience Problem

The licence wall

Count the people in your organisation who can open the architecture repository. In most enterprises it is somewhere between four and fifty. Now count the people who need to know something that is in it: delivery leads planning a release, a risk officer tracing a control, procurement checking whether a capability already exists, the supplier who has to integrate with you next quarter. That number is in the hundreds.

The gap between those two numbers is the single biggest reason architecture repositories fail to earn their keep. It is not a modelling problem. The model may be excellent. It is a distribution problem, and it is usually invisible to the team that maintains the repository, because everyone they talk to has a licence.

What happens instead

When the repository is unreadable to most of its audience, the architecture does not stop travelling. It travels badly. Someone opens the modelling tool, screenshots a diagram, pastes it into a deck, adds three bullets of context, and sends it. That deck is accurate on the day it is made.

Then the repository changes and the deck does not. Nobody withdraws it. It gets forwarded, attached to a business case, quoted in a steering pack. Six weeks later a decision is made against a picture of an architecture that no longer exists, and no one involved has any way of knowing.

This is worth naming precisely, because the usual framing — "we need better communication" — points at the wrong fix. The problem is not that architects communicate badly. It is that every copy of the architecture outside the repository is a fork with no merge path and no expiry date.

The four options

There are really only four ways to close the gap, and it is worth being honest about all of them, including the one most teams end up with by accident.

The fourth option is the one people reach for last and often should have reached for first. If what you need is to put an approved baseline in front of a wide, mostly read-only audience, generating a static site from the repository is the cheapest thing that works. There is no server to secure, no database to back up, no runtime API to break, and no licence per reader.

Snapshot is a feature, not a compromise

The obvious objection to static publication is that it is out of date the moment it is generated. That is true and it is less of a problem than it sounds, for a reason worth thinking through.

A live portal shows you the repository as it is right now — including the half-finished package an architect is mid-way through restructuring, the element someone created to test something, and the diagram that is three shapes into a redraw. For an architect that is exactly right. For a risk officer citing your architecture in a control assessment, it is worse than useless: they cannot quote a moving target.

The thing that makes a snapshot trustworthy is not freshness, it is predictable freshness. A portal republished every Monday at 06:00 is trusted, because a reader can reason about how stale it might be. A portal republished whenever someone remembers is not trusted, because they cannot.

What a portal has to contain to be useful

Publishing diagrams is the obvious part and the least important. A picture answers "how does this fit together". Most of the questions your non-architect audience actually arrives with are lookups:

• Which applications hold personal data, and who owns each of them?
• What does this capability depend on, and what depends on it?
• Which requirements does this control satisfy, and how were they verified?
• When was this last reviewed, and by whom?

Those are table questions, not diagram questions. A published portal that is only a gallery of pictures will get one visit per reader. One that carries the element documentation, the tagged values, the relationships in both directions, a searchable index and a catalogue view will get used, because it answers the question the reader actually had.

The test

Here is a way to find out whether you have this problem, and it takes about ten minutes. Pick a real question that landed in your inbox in the last month — something like "does anything else already do customer deduplication?" Now ask the person who sent it to answer it themselves, using whatever access they currently have.

If they cannot, you do not have a modelling gap. You have a distribution gap, and no amount of additional modelling will close it. The repository already knows the answer. It just has no way of telling anyone.

Counting the cost

It helps to put numbers on this, because "stakeholders cannot read the architecture" sounds like a communication complaint and funds nothing.

Take the three questions your architecture team answers most often. For each, estimate how many times a month it arrives, and how long it takes to answer properly — which usually means opening the tool, finding the element, checking it is current, and writing a reply. Twenty minutes is a fair figure for anything non-trivial.

In a mid-sized enterprise this arithmetic tends to land between two and four days of senior architect time per month, spent transcribing things the repository already knows. That is the recurring cost. The one-off costs — a duplicate integration built because nobody could find the existing one, a decision taken against a stale diagram — are larger and harder to attribute, which is precisely why they keep happening.

Why the fix is usually deferred

Given the cost, the interesting question is why organisations tolerate this for years. Three reasons, all of them rational from where the decision-maker sits.

The people who feel the pain are not the people who own the repository

The architecture team is not inconvenienced — they can open the tool. The delivery lead who waited three days for an answer does not think of it as an architecture repository problem; they think of it as architects being busy.

There is always a workaround

Someone will send a screenshot. The question does get answered, eventually. Nothing fails outright, so nothing escalates. Slow-burning inefficiency with a functioning workaround is the hardest kind of problem to get funded.

It looks like a tooling purchase

Framed as "we need a portal product", it competes with everything else in the tooling budget. Framed as "four senior days a month plus the duplicate-build risk", it competes with nothing, because it pays for itself.

What to do this quarter

Regardless of which of the four options you eventually choose, two things are worth doing immediately and cost nothing.

1. Keep a question log. Every architecture question that arrives from outside the team, with who asked and how long it took. Three months of that log is the entire business case, and it also tells you exactly which content to publish first.
2. Stop producing undated exports. If a diagram leaves the repository, it carries the date it was exported and a line saying where the current version lives. This does not fix distribution, but it stops the silent-drift failure, and it costs one template change.

The meeting where the problem shows itself

If the audience problem feels abstract, sit in on one recurring meeting: the design review where a delivery team presents a change. Watch what happens when the architecture becomes relevant. Someone says "the current landscape is on slide four" — a screenshot, taken at some point, of a diagram that lives in a repository none of the attendees can open. Questions arrive that the slide cannot answer: what else talks to that service, who owns the platform underneath, is the retired flag on that system real. The one person with repository access says they will check after the meeting. The decision gets made anyway, on the slide.

Every part of the dysfunction is visible in that half hour. The screenshot is unverifiable and already stale. The follow-up answer arrives two days later in an email that three of the seven attendees read. The architect's expertise was reduced to a lookup service, and the lookup had a queue. Multiply by every design review, risk assessment and vendor evaluation in the organisation, and the licence wall stops being a procurement detail and becomes the practice's largest single tax on decision quality — paid invisibly, in slides, by people who have never filed a complaint because they have never seen the alternative.

What the authors gain

The case for fixing the audience problem is usually made on the readers' behalf, but the architects themselves collect a return that deserves naming, because they are the ones who must change their habits to realise it.

The interruptions fall first. The daily stream of "can you send me the diagram of…" and "who owns…" — each a context switch costing more than its answer — collapses once the answer has a URL. Architects who measured it informally report reclaiming hours per week, and the questions that still arrive are the interesting ones, the ones that genuinely need an architect rather than a lookup. Authority shifts too: an architecture that people can read gets cited instead of paraphrased, and the practice stops discovering its own work mangled in other people's slide decks. And the feedback loop finally closes — readers who can see the model report what is wrong with it, which no amount of internal review replicates. The repository's audience was never a burden waiting to be served; it was an unpaid quality-assurance department waiting to be let in.

The quarter after the wall comes down

What actually happens when the audience problem gets fixed is worth describing, because it is not the smooth adoption curve the business case promised — it is stranger and better.

The first fortnight is quiet. The link goes out, a few dozen people click, and the practice wonders whether the effort was worth it. Then the first citation appears: a delivery lead pastes a portal link into a design document instead of a screenshot, and the document's reviewers follow it. This is the mechanism by which architecture portals actually spread — not through announcements but through citations, each one an endorsement carried to exactly the people who need the endorsement. By the end of the first quarter the portal's traffic graph shows the signature of organic adoption: spiky, meeting-correlated, and growing at the pace of the organisation's document turnover rather than at the pace of the communications plan.

The second-order effects arrive next, and they are the ones nobody budgets for. The questions reaching the architects change register — from "what talks to what" to "why is it this way and should it stay so" — because the lookup layer of their expertise is now self-service and what remains is the judgement layer, which is both more interesting to answer and more valuable to ask. Model quality rises without a quality initiative, because a readership is the cheapest review process ever invented. And at least one conversation happens that could not have happened before: a business stakeholder, browsing, notices that the architecture's picture of their domain is wrong in a way the architects could never have known — the correction that repays the entire publication effort in one email.

None of this requires the portal to be excellent. It requires it to exist, to be current, and to be reachable without a licence, a ticket or a favour. The audience was always there; the wall was always the only problem; and the quarter after it comes down is when the repository finally starts earning interest on years of deposits.

One caution belongs in the celebration: the wall tends to re-form, quietly, one exception at a time. A new repository module arrives whose content "is not ready to publish"; a reorganisation parks a domain's models behind a temporary restriction that outlives three programme names; a licence renewal shrinks the reader count and nobody renegotiates. None of these announces itself as a return of the audience problem — each is locally reasonable, and their sum is the licence wall rebuilt in eighteen months, with better excuses. The countermeasure is the same one that works for every other slow regression in this series: make openness measurable and reviewed. The portal's coverage — what share of the estate a licence-less reader can actually reach — is one number, computable at every publication, and a practice that watches it will notice the wall going back up while single bricks can still be refused. The audience problem was never solved by the first publication; it is solved by the standing decision, renewed quarterly in front of a number, that the architecture is for reading.