Forty projects, forty dialects
The organisation was a professional services firm — several hundred consultants, a central architecture group of four, and at any given moment somewhere around forty client engagements in flight. Each engagement that involved solution design was expected to model in Sparx EA — in the firm's central Pro Cloud Server repository, one root branch per engagement — and most did, after a fashion. The trouble was the fashion. Every project team opened an empty repository and invented its own world: its own package structure, its own naming habits, its own idea of which diagrams a design needed, its own colour scheme. Two projects run by the same practice lead could produce models that looked like the work of different companies.
The cost of this was not aesthetic. The central group reviewed every significant design before it went to a client, and reviewers were spending the first hour of every review learning the project's private dialect before they could evaluate anything. New joiners assigned to a running project needed weeks to become useful in its model. Content that should have been reusable — the firm modelled the same cloud platforms, the same integration middleware, the same identity setup engagement after engagement — was rebuilt from nothing each time, differently. And a noticeable minority of teams had quietly concluded that the repository was more trouble than it was worth and gone back to drawing architecture in PowerPoint, where nothing about a design can be checked.
The head of the architecture group framed the engagement in one sentence: a new project should start from something, and the something should be good enough that no reasonable team wants to start from nothing.
What twelve project models told us
Rather than start from opinions, we audited twelve recent project models chosen by the client to span practices and sizes. The variation was worse than anyone had guessed. Package structures ranged from a disciplined four-level tree to a single package containing two hundred elements and thirty diagrams. Three projects had modelled the client's Azure identity platform independently, with three names and three levels of detail. Orphan diagrams — views left empty or half-empty after their elements were deleted — appeared in nine of the twelve models. Only five models contained anything a reviewer could recognise as a deployment view, and only two recorded decisions anywhere at all.
The audit also surfaced what was worth keeping. Two projects had developed genuinely good local habits: one kept a read-me diagram at the top of its model explaining the structure to visitors, another maintained a small decision log as stereotyped elements. Both habits survived into the eventual template, with their originators' blessing, which did the adoption cause no harm at all.
We presented the audit as a one-page scorecard per project, anonymised in the group session. Nobody argued with the diagnosis, mostly because everyone recognised their own project in at least one of the failure patterns, and the two good habits gave the conversation something to aim at rather than just something to avoid.
Agreeing the minimum every project produces
The first workshop question was not what a template should contain but what every project, without exception, owes its reviewers. Ambition here is the enemy: a mandatory list that is too long gets ignored wholesale, and then the sensible parts die with the unreasonable ones. After two sessions the list settled at four views: a context diagram showing the solution among its neighbours, an application cooperation view showing structure and information flows, a deployment view showing where things run, and a decision log. Everything else — process views, data models, sequence diagrams — is optional equipment, used when the engagement calls for it.
Getting practice leads to agree the list mattered more than the list itself. We ran the workshops so that the leads proposed and defended the candidates, with us supplying examples and consequences rather than verdicts. The list that emerged was theirs, and when a project later argued for skipping the deployment view, it was a practice lead who said no before we could. That is the difference between a convention and governance that survives contact with delivery pressure.
The starter package
The centre of the solution is a master package — the project starter — that a new engagement pulls into its repository and renames. It contains a numbered package tree: context, business, application, technology, and a ninety-numbered package for decisions, with the numbering forcing a stable order in the Project Browser so that every project reads the same way top to bottom. Each mandatory view exists as a placeholder diagram in the right package, and each placeholder carries its instructions in the diagram notes: what belongs on this view, what does not, and a link to a worked example. The guidance lives inside the model, two clicks from where the work happens, because guidance in a wiki is guidance nobody has open when they are modelling.
Alongside the placeholders sits a small worked example: a fictitious but complete slice of a design, six elements deep, with every convention applied — naming, stereotypes, tagged values, colour. Every example element is stereotyped «example» and rendered in a washed-out grey so it cannot be mistaken for real content, and a start-up script offers to delete the lot once a team has found its feet. The example earns its place because people copy what they see far more reliably than they follow what they read; the grey styling earns its place because of what happened before we introduced it, which we will come to under lessons.
The starter also fixes the small vocabulary that makes models comparable: a naming convention of plain business names without type prefixes, a short list of sanctioned tagged values — owner, status, environment — and a rule that elements representing shared platforms are linked from the firm's common catalogue rather than remodelled. That last rule is what stopped the fourth independent model of the same Azure identity platform.
Diagram templates and default styles
Visual consistency came from diagram templates rather than discipline. We defined template diagrams for each of the four mandatory views, so a new context diagram arrives with the firm's styling already applied: fonts, colours by layer, connector routing defaults. Stereotype appearances were set once, and the starter's template package is registered as the project template package so that new diagrams actually inherit the styling, which means an «external» system looks the same in every model the firm produces, and a reviewer's eye learns to read the diagrams pre-attentively — the way you read a road sign without noticing you are reading.
We also trimmed the toolbox. Sparx EA offers every notation it knows on every day of the week, and for a consultant who touches the tool monthly the full menu is noise. A lightweight MDG Technology restricted the default toolboxes for the firm's diagram types to the element subsets the conventions actually use — the approach we describe in more detail in our piece on custom diagram toolboxes with MDG. The full palette remains available for those who want it; the default path just stopped offering forty element types where nine would do.
Model patterns for the recurring shapes
Certain shapes recur across the firm's engagements: a system integrated behind an API gateway, a three-environment deployment, a managed file transfer, an identity federation. For each we built a model pattern — a small pre-connected fragment with the elements, relationships and a laid-out diagram — and packaged the set so that patterns appear in EA's Model Wizard, where a team can stamp one into their project and rename the parts. A pattern takes a minute to apply and arrives already conforming to the conventions, which quietly does more for consistency than any review checklist.
Choosing the patterns was an editorial job, not a technical one. We drafted candidates from the audit — shapes we had seen rebuilt at least three times — and let the practice leads strike the list down to eight. A pattern library with forty entries is a second documentation problem; one with eight well-chosen entries gets learned by heart.
The common catalogue
The audit's most expensive finding — the same platforms modelled independently, project after project — got its own instrument: a common catalogue package holding the elements every engagement keeps meeting. The firm's standard cloud platforms, the identity setup, the integration middleware, the handful of SaaS products that appear in half the client landscapes: each exists once, named once, owned by the architecture group, in a shared package at the top of the central repository that every engagement branch can see. A project that needs the identity platform on a context diagram drags the catalogue element onto the view rather than creating its own; where a client runs its own deployment of a catalogued product, that deployment gets its own element linked to the catalogue entry it instantiates, so the product references still converge.
The catalogue holds deliberately shallow content. Each entry is the element, a two-paragraph description, a link to authoritative documentation, and the tagged values the conventions require — not an attempt to model the internals of a cloud platform, which would rot faster than anyone would maintain it. The depth question came up in the workshops and the answer we argued for is the one that held: the catalogue exists so that references converge, not so that knowledge accumulates. Knowledge lives in the documentation the entries point at.
Convergence had a compounding effect we only appreciated later. Once forty projects reference one identity platform element, a search for everything touching that platform returns forty projects' worth of truthful answers — which turned a client-side security question that would once have taken a coordination exercise into a ten-minute search. The catalogue is also where retirement gets managed: when the firm swapped its managed file transfer product, the catalogue entry was marked, and every project referencing it was enumerable the same day.
What the starter deliberately leaves out
Half the value of the starter is in its refusals, so they deserve recording. There is no business process modelling in the mandatory set — the firm's engagements vary too much for one process convention to fit, and a mandatory view that is frequently irrelevant teaches people that the mandatory set is negotiable. There is no requirements management structure; engagements inherit whatever the client runs, and pretending otherwise would have made the starter wrong on day one for most projects. And there are no code-level or data-schema conventions, which belong to delivery tooling, not to the architecture repository.
Beyond the handful of stereotypes and tagged values already described, we declined to prescribe metamodel extensions. The starter uses plain ArchiMate and UML with that minimal set, because every stereotype added to a template is a concept every future consultant must learn before their first diagram. Where a practice genuinely needs more — the data practice wanted logical data model conventions — the answer is a practice-specific supplement that layers on top of the starter, versioned and distributed the same way, rather than a fatter core. Two such supplements exist so far, and the core has stayed at a size a new joiner absorbs in an afternoon.
Saying no to plausible additions is the least visible work in a template engagement and the most consequential. Every refusal above was argued for by someone sensible, and any of them would have been fine alone. Together they would have doubled the surface area, and surface area, more than error, is what kills templates.
Distribution through the Reusable Asset Service
Distribution is where template initiatives usually die, so it got real design attention. The mechanism that failed elsewhere — an XMI export on a file share, updated occasionally, imported on trust — was ruled out early: no version identity, no way to know who has what, and a strong tendency to fork silently. Instead the starter, the patterns and the common catalogue live in the Reusable Asset Service on the firm's Pro Cloud Server, published as versioned assets with release notes. A project pulls the current version at kickoff; the registry records versions and dates; and when something needs correcting, the fix ships as a new version rather than as an edit nobody hears about.
The loop closes with feedback. Teams file template friction — a missing pattern, a convention that fights a real engagement — into a small backlog, and a quarterly review decides what changes. The quarterly rhythm is deliberate: fast enough that the template tracks reality, slow enough that projects are not chasing a moving target. Three versions shipped in the first year, each with a one-page changelog, and the changelog is read, because one page is a length people read.
Keeping the pattern current without breaking projects
One limitation deserves honest treatment: a new template version does not propagate into projects that have already started. The Reusable Asset Service distributes cleanly, but what a project pulled in January is what it has in June, and Sparx EA offers no built-in reconciliation between a project's structure and the current pattern. We considered building automatic upgrades and decided against it — rewriting the inside of a live project model from outside is a good way to be hated — and settled for a script that goes beyond the Reusable Asset Service's own compare-against-registry facility — which checks structure, and is worth running first — by diffing a project's package skeleton, naming and tagged-value conventions against the current starter and produces a short report: what is missing, what has drifted, what is new in the template. Teams run it before major reviews. Whether to act on the report is the team's call, which keeps the tool an adviser rather than an enforcer.
A template that must be adopted is a policy. A template that wins on convenience is a product. The second kind survives its author leaving; the first kind rarely survives its author going on holiday.
What it did to onboarding and reviews
Project start-up changed most visibly. Standing up a conforming model had taken a motivated team the better part of a week — usually spread across a month of getting around to it — and now takes under an hour: pull the starter, rename, stamp the relevant patterns, begin. The unmotivated teams benefited more, because the path of least resistance now leads somewhere acceptable. Two of the teams that had retreated to PowerPoint returned to the repository within the first quarter, not because anyone ordered them back but because starting had stopped being the expensive part.
Reviews shortened from both ends. Reviewers stopped spending their first hour on orientation — nearly every model now reads the same way — and started sampling deeper, because knowing where the deployment view lives means noticing when what is on it is thin. The central group estimates a typical design review takes half the elapsed time it used to, and more of that time is spent on the design rather than on the model. New joiners, for their part, learn one structure that every current and future project shares, and the worked example gives them a model of what good looks like before they have produced anything.
Comparability produced a benefit nobody had asked for: with most projects on one skeleton in one repository, the central group can finally run cross-project searches — every decision taken this quarter, every solution touching a particular platform — and get answers instead of forty apologies. The firm's own maturity self-assessment improved markedly on the modelling-practice dimensions within the year, which matches what daily experience says.
A year in, the numbers behave the way you would want. Nearly every new engagement starts from the starter, around thirty projects sit on the current or previous version, and the diff script's reports have shrunk from pages to paragraphs as drift stopped being the norm. The template backlog receives a steady trickle of items — a healthy sign, since a silent backlog would mean people had stopped expecting the template to improve — and the quarterly review clears most of it. None of these measures was expensive to collect; most come straight from the Reusable Asset Service registry and the repository itself, which is where measures should come from if anyone is to believe them.
Making adoption the easy path
We advised against mandating the template in month one, and the client — after some hesitation — agreed. The first quarter was a soft launch: the starter was announced, three volunteer projects used it, and their practice leads talked about it in the language of time saved rather than compliance achieved. By the second quarter the kickoff checklist for new engagements listed pulling the starter as the default first step, with opting out requiring a sentence of justification to the architecture group. Nobody has yet spent that sentence. Making the good path the default path, and the bad path slightly embarrassing, achieved what a mandate would have achieved with far less resentment — and resentment is the medium in which template workarounds grow.
The other adoption instrument was a monthly modelling clinic: an open hour where any team could bring template friction, modelling questions or half-finished views. The clinic surfaced most of the feedback that shaped versions two and three, and it kept the template associated with help rather than with inspection, which for a central architecture group of four supporting forty projects is the only sustainable posture.
What we would do differently
Three things. First, the worked example initially shipped without the «example» stereotype and the grey styling, and within a month a client deliverable went out containing the fictitious payment gateway from the example, renamed but recognisable. The styling was added the same week. Examples must be unmistakably examples; people copy faster than they read, which is precisely why examples work and precisely how they go wrong.
Second, we would appoint the pattern owner before building anything. For the first two quarters the template was collectively owned by the architecture group, which in practice meant the backlog was triaged by whoever felt guilty that week. Naming a single owner — with the quarterly review as their forum — halved the time from feedback to fix, and the template started feeling maintained rather than merely published.
Third, we underestimated the pull towards project-specific forks. Two large engagements copied the starter and then modified their copy so heavily that the diff script output stopped fitting on a page; both later wanted template improvements they could no longer cleanly receive. We now talk about forking openly at kickoff: extending the starter downwards — adding packages, adding views — is free, while renaming or restructuring what the template provides is the step that orphans you, and teams that understand the distinction up front almost always stay on the near side of it.
If your project teams each start from an empty repository and your reviewers are tired of learning a new dialect every month, this is a well-trodden problem with a well-behaved solution — you can reach us through our contact page.
This case study describes a representative engagement pattern. Organisational details are illustrative and do not identify a specific client.