How Often Should Architecture Be Republished?

Freshness is not the point

The reflex when setting up a published architecture portal is to make it as fresh as possible. Nightly, or hourly if the tooling allows. This optimises the wrong variable.

What a reader needs is not the newest possible page. It is the ability to reason about how old the page might be. A portal republished every Monday at 06:00 has a known staleness window of at most seven days. A reader can work with that: they know when to trust it and when to check with an architect. A portal republished "when we get round to it" has an unbounded window, and the rational response to an unbounded window is to distrust everything on the page.

Choosing the window

Work backwards from the decisions your readers make. If someone uses the portal to decide whether an integration already exists before scoping a new one, ask how often that answer changes. In most enterprises, genuinely new applications appear a few times a quarter. A weekly publication is more than sufficient; a nightly one changes nothing except your infrastructure bill.

Two situations justify a shorter window:

• An active transformation. During a large programme the target architecture genuinely moves week to week, and a monthly portal will be quoted against decisions that have already been superseded.
• The portal is the handover artefact. If delivery teams are expected to pick up architecture from the portal at sprint boundaries, publish before the boundary, not after it.

Publish on a boundary people already have

A detail that matters more than it should: align the publication with a rhythm your organisation already runs on. Monday morning before stand-ups. The day before the architecture board. The first working day of the month.

This does two things. It makes the portal's currency predictable without anyone reading documentation, and it means the freshest version exists at the moment of highest demand. A nightly publication that lands at 03:00 on a Wednesday has no such anchor, and readers end up treating it as perpetually indeterminate anyway.

Say the cadence on the page

Whatever you choose, put it where the reader will see it — in the footer, on the landing page, next to the generation date. Two sentences:

That second clause matters as much as the first. It tells readers what to do when they find an error, and it protects the repository from becoming a place where corrections are made in the published copy and lost.

What breaks a schedule

Scheduled publication fails in predictable ways, and all of them are quiet failures — the portal simply stops updating and nobody notices for a month.

The last mitigation is the cheapest and the most effective. If every page carries the date it was generated, a stalled schedule becomes visible to every reader rather than only to whoever owns the job.

More than one audience, more than one cadence

The question "how often should we republish" quietly assumes one portal, and mature estates rarely have just one. The same repository typically feeds several publications for several audiences: the internal working portal the architects and delivery teams live in, a curated subset for a partner or a supplier, perhaps a programme-specific view assembled for a transformation board. Each is a separate publication with its own scope, and there is no reason they must share a clock.

Letting each audience have its own cadence resolves tensions that a single schedule turns into arguments. The internal portal runs weekly, because that is the rhythm of the work. The partner subset runs monthly, because partners act on it quarterly and every publication to an external audience is a disclosure decision worth spacing out. The programme view publishes two days before each board, on the board's calendar rather than the practice's, and retires with the programme. One pipeline, several configurations, several schedules — the marginal cost of an additional publication is a config file, which is precisely the economy the pipeline was built to enable.

The one discipline multiplication demands is naming. Each publication states what it is, whom it is for and when it refreshes, on its own landing page — because the failure mode of multiple portals is a reader quoting the partner subset in an internal meeting, unaware that the thing they are missing was deliberately not shown to them.

The change log turns cadence into communication

A fixed cadence has a by-product that most portals waste: every publication has a predecessor, and the difference between the two is computable. Two snapshots diffed produce the week's architectural news — elements added, retired, re-related, re-owned — and that list, rendered as a "what changed this week" page and a short notification, changes the portal's relationship with its readers from pull to push.

The effect on adoption is out of proportion to the effort. Readers who would never browse the portal speculatively will skim a weekly change list in the time it takes to drink a coffee, and every scan re-anchors the portal as the place where change becomes visible. Architects gain something too: the list is a public record that the model is alive, which answers the "is anyone actually maintaining this" scepticism more convincingly than any assurance. And the discipline loops back into modelling quality — when every rename and retirement will be announced to a hundred readers on Monday, tag-tidiness and naming conventions acquire an audience, which is the cheapest enforcement mechanism a convention can have.

The change list needs one editorial rule: it reports model changes in business vocabulary, not tool vocabulary. "Payment Gateway marked for retirement, replacement planned Q2" is news; "47 elements modified" is a checksum. The difference is a mapping table and a little care in the generator, and it decides whether the Monday email gets read or filtered.

A reasonable default

Weekly, early on the first working day, with the generation date on every page and an alert when a run fails. Move to nightly only when you can name the decision that a six-day-old answer would have got wrong. In several years of doing this, that conversation has ended in "weekly is fine" far more often than not.

The out-of-band run, done properly

Rejecting the on-demand button does not mean pretending extraordinary publications never happen. A merger closes, a security incident redraws a perimeter, the board moves its meeting — sometimes the portal genuinely must update between Mondays, and a practice that cannot do it will do something worse instead, usually involving a PDF assembled by hand at ten in the evening.

The discipline is that an out-of-band run is the same pipeline in every respect but its trigger: same extraction, same quality gate, same verification, same notifications. What changes is the record — the publication announces itself as extraordinary, with a reason and a requester, both on the portal's change log and in the run history. That one line of provenance is what separates "we can respond to events" from "the schedule is negotiable". The test of whether the practice has this balance right is the count: a handful of extraordinary runs a year, each with a reason a stranger would accept, is a healthy sign of a portal that matters. One a week is a schedule that has quietly stopped being one, and the fix is to move the schedule, not to keep overriding it.

Cadence and the model's own rhythm

A publication schedule interacts with how the repository is edited, and getting that interaction wrong produces portals that are technically current and practically misleading.

Most architecture teams work in bursts. A modelling session before a board, a flurry of changes during a design authority cycle, then weeks of relative quiet. A publication that lands mid-burst captures a model halfway through a restructuring — the old package deleted, the new one not yet populated — and publishes it as though it were a considered state.

Two defences. Publish from an approved baseline rather than from current state, so mid-flight work is never picked up. Or, if you publish current state, schedule the run for a time when the repository is reliably quiet and accept that the answer is "early morning".

Publishing more slowly than you model

The discussion so far has pushed against publishing too eagerly; the opposite end of the spectrum deserves a word, because it is where regulated estates often correctly live. Nothing requires the portal to track the repository's working state at all. A practice can model daily and publish monthly, from approved baselines rather than from whatever the repository contains on Monday morning — and for architecture that feeds formal governance, that is not conservatism, it is the design.

Baseline-driven publication changes what the portal claims. A current-state portal says "this is what the repository contained at 06:00"; a baseline portal says "this is what the design authority approved on the 4th". The second claim is stronger, slower, and for some audiences the only one worth making — an auditor sampling controls, a regulator reading a submitted architecture, a supplier contractually bound to a version. The staleness window is wider, and it is bounded by something better than a schedule: a decision, with minutes and signatures, whose date the portal displays instead of a generation timestamp. Publication as evidence more or less requires this shape.

The pattern that serves both masters, and that most estates with governance obligations converge on, is two publications from one repository: a weekly working portal, clearly labelled as current state and subject to change, and a baseline register that updates only when a baseline is cut. Readers self-select accurately once the labels are honest — delivery teams live in the first, assurance lives in the second, and the practice stops trying to make one artefact satisfy two incompatible definitions of "reliable".

When to change the cadence

Cadence is not a decision you make once. Three signals suggest it needs revisiting:

• Readers are asking whether a page is current. The window is too wide for the decisions they are making, or it is not visible enough on the page.
• Nothing changes between publications. You are paying for runs that produce identical output. Lengthen the interval and spend the attention elsewhere.
• People are asking for out-of-band publications. A recurring request to "republish now, we have a board tomorrow" means the schedule is not aligned to the organisation's rhythm.

That last one is worth acting on rather than accommodating. An on-demand publication button seems helpful and quietly destroys the property that made the portal trustworthy — a reader can no longer reason about staleness, because the schedule is no longer the schedule.

Starter schedules that work

For a practice setting this up from nothing, the following set covers the common cases and can be adopted as-is, then adjusted when a real signal — not a hypothetical one — says otherwise:

Each row carries its cadence on its own landing page, each runs through the same gates, and each failure alerts the same owner. Start here, watch the three signals described above for a quarter, and adjust one row at a time — which is the entire operational discipline of publication cadence, and pleasingly little of it.

The economics, honestly

One argument has been conspicuously absent from this discussion: cost. That is deliberate, because for a well-built pipeline the marginal cost of a publication rounds to zero — some minutes of compute on a machine that exists anyway, a static deployment measured in megabytes. Anyone arguing cadence on infrastructure cost is arguing about the wrong resource. The scarce resources are attention and meaning, and they point in opposite directions from cost.

Attention: every publication is a potential failure that someone must be able to investigate, and a failed nightly run at 03:00 Tuesday competes for the same person as everything else broken that morning. Fewer, better-attended runs beat many ignored ones. Meaning: a publication event that happens constantly stops being an event. When the portal updates weekly, "it changed" is information and the change log is news; when it updates hourly, change is weather. The staleness window argument from the top of this article is really a statement about meaning — a cadence is a promise, and promises kept on a human rhythm are the ones humans can build habits around.

So the closing advice stays where it started, with numbers attached. Weekly, published before the week starts, costs perhaps ten minutes of compute and one glance at a green notification; it gives readers a seven-day window they can reason about, a Monday change list worth reading, and an operations story one person can own alongside a day job. Everything faster should be justified by a named decision that could not wait six days — and in our experience, when that decision is finally named, it usually turns out to want a baseline register or an extraordinary run, not a faster clock.

The first Monday

A closing image, because cadence is finally about habit rather than machinery. The first scheduled Monday publication is an event: someone watches the run, someone checks the pages, someone sends the link around. By the fourth Monday nobody watches, and by the tenth the portal's freshness has become ambient — a fact about the environment, like the coffee machine working, noticed only in its absence. That is the success state, and it is worth telling the team in advance that anticlimax is the goal.

The habit forms on the reader side too, and faster than expected. Within a quarter, people schedule around the cadence without thinking about it — the architect who tidies element ownership on Friday afternoons because Monday is coming, the delivery lead who checks the change list before sprint planning, the PMO that pulls its numbers on Mondays because that is when the numbers are new. None of them were instructed; the rhythm taught them. Choose the cadence once, keep it religiously, and it stops being a technical parameter and becomes what it always really was: the portal keeping its word, weekly, until trust is simply assumed.