Taste becomes structure
A single architect can name things however they like. They remember what they meant, they know where everything is, and no automated system depends on their choices.
Put the same model in a shared repository with search, scoped permissions and cross-project references, and those choices stop being taste. The search index only finds what was named findably. Permissions only scope what was filed in the right project. A reference only resolves if the thing it points at was not duplicated under a different name.
Naming: for the searcher, not the author
The most common failure is naming from the author's context. Gateway is unambiguous to the person who created it inside the payments model and useless in a search returning results from eleven projects.
Three rules cover most of it:
- Name what a stranger would call it. If the team says "the payment hub", the element is Payment Hub, not
PMT-ORC-01. - No abbreviations that are not universal in the organisation. If a new joiner would not recognise it in week one, spell it out.
- Do not encode metadata in the name.
Payment Hub (deprecated, Jan)should be a lifecycle property and an owner property. Names in parentheses are a symptom of missing fields.
One concept, one element
The single most damaging thing that happens in shared repositories: two architects independently create an element for the same real thing. Now half the relationships attach to one and half to the other, and every analysis is quietly wrong.
This is a search problem before it is a discipline problem. Architects duplicate because they looked, did not find it, and reasonably concluded it did not exist. If your repository has good cross-model search and people are trained to use it before creating, duplication drops sharply without anyone being told off.
Where duplication has already happened, resist mass merging. Fix it where it matters — the elements that carry relationships and appear on published views — and let the long tail alone. A cleanup project that touches everything will not finish.
Structure follows permissions
Once permissions are scoped to projects, the project boundary is no longer just an organising convenience. It determines who can see what.
This has a practical consequence people meet late: an element in the wrong project is invisible to the team that needs it, or visible to a team that should not have it. "Where does this live" becomes a decision with an access-control implication, and it is worth agreeing the shape of the estate before granting the first permission rather than after.
Documentation: two sentences, always
A convention worth enforcing because it is cheap and compounds: every element that anyone outside the authoring team will see gets at least two sentences. What it is, and what it is for.
The reason is search and publication. An element name in a result list with no description is a guess; the same result with two sentences is an answer. Multiply by a thousand elements and it is the difference between a repository people use and one they give up on.
Enforce a little, automatically
Conventions that live in a document are aspirational. A small number checked automatically — on publish, or on a nightly scan — are real.
Start with three: canonical elements have an owner, elements visible outside their project have documentation, and no two elements of the same type share a name within a repository. Report rather than block at first. Once the list is short enough to be worked through, promote the ones that matter to blocking.
Conventions that need to be agreed before migration
Some conventions can evolve. A few are structural and are painful to change once models are in the repository and permissions have been granted against them.
- What a project is. A delivery project, a domain, a team? It becomes the permission boundary, so this decision outlives whatever prompted it.
- Where shared elements live. Deciding this after the fact means moving elements between projects, which breaks references and changes who can see them.
- Model granularity. One model per project or several? This determines the lock granularity and therefore how often people collide.
None needs to be perfect. All are worth thirty minutes of deliberate conversation rather than being settled by whoever migrates first.
Enforcement that people accept
Automated convention checking succeeds or fails on tone.
A check that blocks a publish because an element lacks documentation will be worked around within a week — people will type a full stop in the field. A check that reports, weekly, which elements in your area lack documentation, gets acted on, because it is information rather than an obstacle.
Reserve blocking for things that genuinely break something downstream: a duplicate name that makes search ambiguous, a missing owner on an element other teams depend on. Everything else reports.
Write them down where the work happens
Conventions live in a wiki page that was written once, read by the three people who wrote it, and never opened again. Everyone knows this and everyone does it anyway, because the alternative requires the conventions to be somewhere the modelling tool can reach.
The version that survives puts each convention as close as possible to the moment it applies. A naming rule belongs in the validation that runs when a model is published, not in a document. A rule about which package a new application goes in belongs in the package structure itself, as a folder called what it is for rather than what it contains. A rule about mandatory properties belongs in the metamodel, where the field is simply required.
What is left over after that — genuine judgement, like when to model a capability versus a process — is the only part that needs prose, and it should be short enough that a new joiner reads all of it. Two pages. Anything longer will be skimmed, and the parts that get skimmed are indistinguishable from the parts that were never written.
Onboarding a new modeller
The real test of a convention set is whether someone who joined last week produces work that looks like everyone else's. Most estates discover the answer is no, three months later, when the new person's domain turns out to be structured differently from every other one.
What closes that gap is not a longer document. It is a worked example: one domain, modelled properly, that a newcomer is told to copy the shape of. People imitate far more reliably than they follow rules, and a reference domain answers a dozen questions that no convention document anticipated.
Pair it with a review of the first thing they publish. Not a governance review — a fifteen-minute look by someone experienced, before it becomes twenty elements everyone has to live with. This is the single cheapest quality intervention available and it is almost never done, because it requires an hour from someone senior at exactly the moment they are busiest.
Conventions that stop being right
Every convention set contains at least one rule that made sense for the estate as it was three years ago and is now actively harmful. It survives because nobody has standing to remove it and everyone assumes there was a reason.
The common examples are recognisable. A naming rule that encodes an organisational structure which has since been reorganised, so element names now reference departments that no longer exist. A package hierarchy built around a programme that finished. A mandatory property nobody uses, which is now populated with placeholder text across four hundred elements because it blocks publication.
The fix is procedural and cheap: once a year, list every convention and ask of each one what would break if it were dropped. Rules that nobody can answer for get dropped. This meeting takes an hour and it is the only mechanism that removes anything, because in the normal course of events conventions are only ever added.
Where automation helps and where it backfires
Automated enforcement is the obvious answer and it has a failure mode worth understanding before switching it on: a validation rule that fires too often trains people to ignore validation.
A publish that reports two hundred warnings gets skimmed and dismissed, and the three warnings that mattered go with it. Worse, the team develops a habit of clicking through the report, which persists after the noisy rules are fixed.
The rule for what to automate is whether the check is unambiguous and the fix is obvious. "This element has no owner" qualifies: there is no judgement and the action is clear. "This relationship type may be wrong here" does not — it is a matter of interpretation, it will be wrong a third of the time, and after a fortnight nobody reads it.
Everything ambiguous belongs in a report a person reads periodically, not in a gate that blocks a publish. The distinction is between checks that assert facts and checks that offer opinions, and only the first kind should be able to stop someone working.
The conventions that only matter at scale
Some rules are pure overhead in a two-architect estate and become load-bearing at fifteen. Adopting them early is a cost; adopting them late is a migration. Knowing which is which lets you decide deliberately.
- Identifier stability. Never reuse an identifier, never renumber. Irrelevant with one modeller, essential once anything external references elements — a portal URL, a spreadsheet, a linked requirement.
- Ownership of packages, not elements. Fine-grained ownership is manageable at small scale and unmaintainable at large. Deciding this early avoids a permission model that has to be rebuilt.
- A rule about what is not modelled. Small estates model whatever seems useful. Large ones need an explicit boundary, or the estate accumulates servers, licences and org charts and stops being an architecture.
Handling the modeller who disagrees
There is always one, and they are usually the most experienced person on the team. They have a way of modelling that works, it predates the conventions, and it is not obviously worse — it is just different, and different is the entire problem.
Two things are true at once. Consistency is worth more than local optimisation, because an estate where every domain is modelled slightly better in a slightly different way is unusable. And an experienced modeller objecting to a convention is often objecting to something genuinely wrong with it.
The way through is to make the convention set changeable and then hold people to it. If there is a route to argue a rule and win, following the rules you lost on becomes reasonable. If the rules are immovable, the only options are compliance and quiet deviation, and experienced people choose the second.
Measuring whether conventions are holding
Conventions decay invisibly. The estate looks fine because nobody looks at all of it at once, and the divergence is only apparent when someone tries to generate a catalogue and finds four naming styles.
Three numbers, run monthly, catch most of it. The proportion of elements matching the naming pattern — a regular expression, not a judgement. The number of distinct element types in use, which should be stable and creeps upward when people invent stereotypes. And the proportion of elements with all mandatory properties populated, tracked as a trend rather than a target.
None of these measures quality. They measure consistency, which is the thing conventions exist to produce, and a downward trend on any of them is a signal months before anyone would otherwise notice.
A starter set to adopt on Monday
For a team that would rather begin than deliberate, here is the convention set we hand to practices at migration time — small enough to fit on one page taped to a monitor, complete enough to survive the first year.
Naming: business-meaningful, no version numbers, no status suffixes, acronyms only when the business itself uses them, and the searcher's phrasing wins every argument — if delivery teams say "CRM", the element carries CRM somewhere findable. Identity: one concept, one element; before creating anything, search for it, and treat a failed search that produces a duplicate as a naming bug to fix, not a personal failing. Structure: packages follow domains and permissions, never people; if a package is named after a colleague or a committee, it is in the wrong taxonomy. Documentation: two sentences on every element that leaves the team's own package — what it is, why it matters — written for the reader who arrived from search with no context. Properties: only the agreed keys, from the controlled lists, with owner and lifecycle mandatory on anything published. And relationships: typed deliberately, because the notation will be rendered faithfully and a wrong arrow publishes as confidently as a right one.
Six lines, teachable in an hour, checkable by the gate for the mechanical half and by review for the rest. Teams refine from here — every estate grows its local additions — but the refinements argue with a working baseline instead of with a blank page, and that difference is measured in months. Conventions are like style guides everywhere: the best set is not the ideal one, it is the adequate one that everybody actually follows, adopted early enough that following it never felt like a change.
Conventions are the least glamorous artefact an architecture practice produces and the most load-bearing: every search hit, every portal column, every permission boundary and every merge-free week stands on names chosen consistently by people who never met. Write the six lines down, enforce the checkable half, and let the estate's own legibility make the case for the rest — it will, every time someone finds what they were looking for on the first try.
And when a convention argument does flare up — the singular-versus-plural debate, the great acronym war — settle it fast and shallowly. Most convention questions have no right answer, only a consistent one, and the estate is served better by an arbitrary rule everyone follows than by a principled debate that runs for a quarter. The practice lead's most useful sentence in these moments is also the shortest: "decided; next item." Consistency is the deliverable; correctness was never on offer.