The first year was chaos. Then we wrote it down.

The first year was chaos. Then we wrote it down.

Early on, before any of this was written down, the same agency’s sites were being built three different ways.

One developer was using Elementor Forms because it was already in the layout. Another was switching them out for Gravity Forms. A third was leaving the existing forms alone, on the grounds that “if it works, don’t touch it.” This was the very beginning — there was no standard yet, on our side or the agency’s. Three different builds. Three different form behaviours. Three different review threads for the same kind of question.

That was the cleanest of the disagreements.

There was also the question of which CSS units to use. Whether to leave the WordPress sample page in or delete it on day one. Whether headings should be Title Case (Personal Injury) or sentence case (Personal injury). Whether the homepage’s hero needed a custom breakpoint, or whether the default Elementor breakpoints were fine. Whether to install a caching plugin on WP Engine. (WP Engine has caching built in. The plugin doubles it. That fact was not common knowledge across our team in the first 6 months.)

Every one of these had a right answer, and at the start every one had more than one version of the wrong answer running on different sites.

The agency noticed too. It did not come up often (maybe twice across the whole stretch), but when it did, the conversation had the same shape: this site does X, the previous one did Y; can we settle on one? And the honest part is that the agency did not have a fixed standard either. The lane we eventually picked, we picked together.

We could not point to a single lane, because there wasn’t one yet. Each developer had landed on a personal default through a mix of habit, browsing the project’s existing setup, and assumptions about what the agency wanted. None of those defaults aligned. The result was a quality that was technically passable on every individual site and visibly inconsistent across the portfolio.

That was the pain. The cure was not training, but writing it down.

What “writing it down” actually means

The temptation, when a team’s outputs are inconsistent, is to schedule a meeting. Get everyone in a room, walk through the conventions, agree on the standards, move on. We tried that. It works for one week. By the second week, half of what was agreed has dissolved back into “well, on this project I thought…” and the other half has fragmented into competing interpretations.

What actually shifted things was the slow accumulation of a written guideline, one rule at a time, each rule attached to a real conflict that had cost real time. The first version had 5 rules. The current version has more than 30. Almost every rule traces back to a specific moment of friction we wanted to never have again.

The current internal version of the document opens like this:

# xpro · WordPress build conventions
# v17 — 2026-04-30

stack:
  page-builder:  elementor-pro-only
  forms:         gravity-forms          # not Elementor Forms
  seo:           rank-math
  caching:       none                   # WP Engine has built-in cache
  hosting:       wp-engine-standard     # agency-supplied environment

content:
  heading-case:  title-case             # "Personal Injury", not "Personal injury"
  h1-per-page:   1
  units:         px-only                # no vw, no clamp without justification
  breakpoints:   elementor-defaults     # custom breakpoints disabled

phone-numbers:
  format:                  tel:+1XXXXXXXXXX
  always-clickable:        true
  always-include-country:  true

Each line is a settled argument. Most took a project to settle.

A few examples with their hidden histories:

“Use Elementor Pro for all page building.”
We build everything on Elementor — that part was never really in dispute on our side. The rule is written down anyway, because “obvious to us” is not the same as “documented.” More than once, a build looked like it had been assembled two different ways, and tracing it back, the inconsistency came from how the project had been set up before it reached us, not from a developer swapping builders mid-project. Writing the rule down made the expectation explicit instead of assumed, for us and for the agency.

“Gravity Forms only. Do not use Elementor Forms.”
Gravity Forms had the agency’s stable email-deliverability setup, the conditional logic the agency relied on, and the tracking integrations that fed into their reporting. Elementor Forms is a perfectly reasonable plugin for a different kind of project. On these projects, mixing the two meant some forms had analytics and some did not, some had spam protection and some did not, and the agency’s review process had to discover this for each new site. The rule wasn’t about the better plugin. It was about not having two answers to the same question.

“WP Engine has built-in caching. Do not install caching plugins.”
This one cost 4 hours of debugging on a staging environment that kept serving stale assets after a deploy. The cause was a caching plugin installed out of habit, sitting on top of WP Engine’s own cache layer. Two caches, racing each other. The fix was to remove the plugin. The rule was to not install it next time.

“Phone numbers must use the tel:+1XXXXXXXXXX format. Always include the country code.”
For a while, phone numbers were going onto pages inconsistently — some as plain text with no tel: link, some with no country code, some done properly. A number rendered as plain text won’t trigger the dial dialog when a visitor taps it on a phone. The inconsistency was the actual problem, not any single rendering. The fix was to pick one format and use it every time. The rule is those few characters, written down so the question never reopens.

“Headings and menu items use Title Case for each word.”
This is the kind of detail that looks petty until you’ve reviewed a stack of sites in a week. Some used Personal Injury and some used Personal injury. Both are defensible style choices. Neither is defensible together. We had simply let it drift. It was nobody’s deliberate decision, which is exactly why only a written rule could close it.

“Pixel units only. No vw, no clamp unless explicitly required.”
This rule looks like a constraint on creativity. It is not. It is a rule about predictability. A site built with clamp and vw looks fine on the developer’s monitor and unpredictable everywhere else. The agency’s reviewers were on a mix of laptops, tablets, and external displays at different scaling settings. A pixel-based layout was the same on all of them. A responsive-units layout was several different layouts. The rule wasn’t about taste in CSS. It was about giving the reviewer the same site we built.

“One <h1> per page. Follow the heading hierarchy.”
The agency kept flagging the same thing across builds: pages with more than one <h1>. It happened because a developer dropped in a hero widget configured as <h1>, then dropped in a section heading also configured as <h1> because it looked correct visually. The browser doesn’t care; an audit does. The rule wasn’t about SEO theory. It was about not redoing the heading hierarchy every time it was flagged.

“Disable Elementor’s custom breakpoints. Use only the defaults.”
This one came from a mismatch, not a single incident. We were testing builds at one set of breakpoints; the agency was reviewing at another. Layouts that looked correct to us looked broken to them, and the other way round, with no one actually being wrong. The fix wasn’t to argue about whose breakpoints were better. It was to agree on one shared set and disable everything else. Default breakpoints are documented, predictable, and the same on both sides of the review.

We could keep going. There are rules about which fonts to load through TypeKit and which never to upload manually. Rules about which sitemap entries to include and which to suppress. Rules about how to mark a target="_blank" on outgoing links. Rules about removing the WordPress sample page on day one. Rules about UpdraftPlus during development.

None of them are clever. All of them are settled.

What changed when the document existed

The thing we did not predict was where the benefit actually landed. It was not mostly on our side. It was on the agency’s.

Before the document, the agency had to review our builds the slow way — opening pages, checking conventions by hand, re-litigating the same questions on each new site, because they could not assume any two builds would be consistent. After the document, the builds were consistent enough that the agency could stop doing that. They leaned on an automated check to surface anything off, and reacted to what it flagged, instead of manually re-reviewing conventions from scratch every time.

That is the whole story of what changed: the review burden came off the agency. Not because they trusted us more in the abstract, but because consistency is checkable and inconsistency is not. A written standard is what made the builds checkable in the first place.

The lesson for the agency

If you are a marketing agency that subcontracts WordPress builds (to one shop or to many), the absence of a written guideline is a tax that you are paying every week. You do not see it as a tax. You see it as “the normal cost of working with developers.” It is not normal. It is the cost of letting each developer reinvent the conventions of your portfolio, and then absorbing the resulting inconsistency through your reviewers’ time.

Two practical observations from our side of this:

One. A guideline document does not need to be perfect to start. 5 rules, written down and agreed, will save more time in their first month than a 50-rule document that took six months to draft. Start with the conflicts you have already had. Add a rule each time a new conflict surfaces. Within a year, you will have something serious. Within two, you will wonder how you worked without it.

Two. When evaluating a new development partner, ask if they have such a document — not as a marketing artefact, but as a working internal standard. A partner who can hand you a written guideline they actually use is a partner whose builds will be predictable across projects. A partner who cannot is offering you their first year of chaos as your first year of supervising them. You can choose to absorb that cost — sometimes the partner is worth it. But the cost is real, and you should know you are paying it.

The first year of working without conventions is unavoidable, the first time. The second time is a choice.

We chose to write it down. Most of what we now produce as a practice is downstream of that single decision.