The Design Decisions Document

Part 3 of “The Landing Zone That Survived” — a year in the life of a New Zealand platform team, told from fakey.xyz. Fictional organisation, aggressively fake people, realistic problems.

Recap. In Part 1, Fakey McFakerson got the mandate, the funding reality, and a 1.6 FTE team. In Part 2, Discovery Week produced a requirement register with named sources, a control triage agreed with Serge Secure (31 ENFORCE / 168 OBSERVE / 15 ENABLE), a finance mapping from Tessa Spreadsheet, and a list of things discovery itself got wrong. Now the team has to turn all of that into something nobody enjoys but every landing zone needs: a set of decisions, written down, with the arguments attached.

There is a document that exists at every stage of every landing zone programme, and it is almost always wrong in one of two ways.

The first way is the diagram without a defence: an architecture document with Visio boxes and no recorded reasoning. Six months later, when someone asks “why is the fraud workload’s traffic inspected?”, the answer is silence, because the person who decided it has moved on and the reasoning lived in their head.

The second way is the defence without a decision: forty pages of options analysis, trade-off matrices, and thoughtful prose that ends, exhausted, without actually choosing anything.

fakey.xyz’s design document was built to avoid both. It has one rule, enforced by Fakey and grudgingly loved by everyone:

Every decision in the document must survive one question: “What would have to be true for us to change this?” If nobody can answer it, it isn’t a decision — it’s a preference wearing a suit.

Here’s how the four biggest arguments went.

Argument One: The Subscription Strategy, or “What Is a Subscription Actually For?”

This was the first and longest argument. It lasted three working sessions and one very tense whiteboard. Participants: Fakey, Robbie Deployment, Tessa Spreadsheet (for finance), and — for two sessions only, by Fakey’s careful design — Serge Secure.

Robbie opened with the engineer’s default: one subscription per environment, per application. Simple, symmetrical, easy to script.

Tessa opened with the finance default: one subscription per product line. Because that’s how the board report works, and if cloud spend doesn’t roll up to product lines without a manual mapping, she will — as she memorably put it in Discovery Week — tell everyone the platform has failed, and she knows all of them.

Both defaults are defensible. Both are wrong as a primary boundary, and the argument that exposed why is the one worth reproducing.

Fakey’s framing, which ended the stalemate:

“A subscription is not an organisational unit. It’s an isolation boundary with billing attached. So the question isn’t ‘how do we organise?’ — it’s ‘what do we need to isolate, and who needs the bill?‘”

Working through that lens, three isolation needs surfaced, in priority order:

1. Compliance scope. Discovery Week revealed the customer onboarding workload (Hugh Documents’ team — passports, driver licences) has the strictest data classification in the company, with residency pinned to Azure NZ North. The fraud platform touches transaction data with CPS 234 implications. These workloads need to be countable — when MegaCorp Megalodon’s auditors, or the Reserve Bank’s, ask “which environments process this class of data?”, the answer must be a subscription list, not an archaeology project.
2. Cost accountability. Product lines need bills that map to finance codes. (Tessa’s requirement, non-negotiable, now with the weight of Discovery Week behind it.)
3. Blast radius and quota. One team’s mistake — a runaway autoscaler, a quota exhaustion, a misconfigured peering — should not be able to degrade another team’s environment.

The decision that emerged, and went into the document:

Primary subscription boundary: product line (maps to finance codes — Tessa’s model wins for the primary axis). Within each product-line subscription set: workloads with elevated data classification get their own subscription (onboarding first; fraud’s scoring stack when it migrates). Environments (dev/test/prod) are separated by management group placement and RBAC, not by subscription — with one exception: any production environment handling regulated personal data gets subscription-level separation from its own non-production, because the audit story is cleaner when the boundary is enforced by ARM, not by convention.

Robbie’s environment-per-subscription instinct wasn’t discarded — it was deferred with a trigger: “If a product line’s environments need different network fences or different policy regimes, split then, deliberately, with the decision documented.” That’s the “what would change this” answer, written down, which is what made it a decision instead of a preference.

The subsidiary decisions fell out fast once the primary axis was settled:

• Management group hierarchy: shallow. Platform / Landing Zones (with Prod, Non-Prod, Sandbox children) / Decommissioned. Fakey killed a proposed six-level hierarchy in one sentence: “In an organisation of 400 people, every management group level is a place governance goes to hide.”
• Sandbox subscriptions exist from day one. Discovery Week’s honest answer about workstations under desks is that people experiment regardless. Give experimentation a cheap, contained, auto-expiring home, or it will find an unsafe one.
• Naming and tagging are policy-enforced, mapped to finance codes. Tessa’s verbatim threat is now a requirement register entry with a source and a stakeholder.

Argument Two: The Network, or “Netty Latency Ruins the Simple Diagram”

The preliminary sketch everyone had in their heads from before Discovery Week: a classic hub-spoke, Azure Firewall in the hub, all inter-spoke and internet traffic inspected centrally. Textbook. Defensible. And — after Discovery Week — carrying a known flaw with a name on it: Netty Latency’s 8-millisecond fraud scoring budget.

The argument happened in a session Fakey structured as options, not positions, with Netty present. Three options on the whiteboard:

Option A: Classic hub-spoke, central inspection. All spoke-to-spoke flows through the hub firewall. Simple to operate, clean to audit, one policy point. Cost: a firewall hop on every east-west flow. Against Netty’s budget: risky, possibly fatal.

Option B: Spoke-direct, minimal hub. Spokes route to each other directly (peering or routed via hub without inspection), internet egress locally with cloud-native controls. Fastest possible east-west. Cost: inspection coverage is much weaker; Serge’s ENFORCE list visibly suffers.

Option C: Hybrid — central inspection for north-south and most east-west, with a documented, policy-gated “low-latency corridor” between the fraud scoring stack and the transaction stream, justified by the measured latency budget, monitored, and reviewed.

The room landed on C, but the reason it landed is the instructive part. Netty didn’t win by asserting sub-5ms — assertions are just positions. She won because the team measured: a proof-of-concept flow through an Azure Firewall Premium, run by Robbie in a test subscription, showed ~1.9ms added per firewall hop — survivable on paper, but Netty’s budget is total, shared with the application, TLS, and the scoring model itself, and her SLO failure mode is a public incident, not a meeting. Combined with the fact that only two service pairs actually needed the corridor, the blast radius of the exception was small and bounded.

What made Option C safe enough for Serge to accept — and this is the sentence Fakey wrote into the document, and the sentence this whole series keeps circling:

“An exception to the inspection standard must be visible, measured, owned, and reviewed — or it is not an exception, it’s a hole.”

The corridor is implemented as policy-allowed flows between named subnets, logged to the central workspace with the same rigour as inspected traffic, with a named owner (Netty) and a quarterly review against her actual SLO data. Serge accepted it because he can see it. The exception register earned its first, most contentious entry on day one — which turned out to be the best possible shakedown test of the register itself.

Everything else in the network decision was deliberately boring: hub in Azure NZ North, Azure Firewall Premium in the hub, private endpoints for PaaS with DNS resolved from the hub (the argument about private DNS zones took forty-five minutes and ended with “standard ALZ pattern, documented, move on”), site-to-site VPN to the Petone colo for the migration period, and a documented note that ExpressRoute gets evaluated when migration traffic volumes justify it — not before, because gold-plating connectivity for a workload profile that doesn’t exist yet is how networks become datacentre replicas.

Argument Three: Landing Zone Code — Bicep, Terraform, and a Condition

The IaC argument was the shortest, because it was really a staffing argument in disguise.

Robbie Deployment is a Terraform person. The wider engineering organisation is GitHub Actions and a smattering of Bicep. The ALZ ecosystem supports both well. Robbie opened with “Terraform, obviously.” Fakey opened with “obviously why?”

The reasoning that settled it, in the document:

Terraform. Reasons: the ALZ Terraform accelerator is mature; Robbie’s depth is real depth and a 1.6 FTE team doesn’t get to learn on the job; the hiring market for platform engineers in NZ reads Terraform fluently — which matters because Robbie will not be here forever (see below); and module reuse for subscription vending is strongest in the TF ecosystem.

But the decision came with the condition — the one Fakey attached in Part 1 when Robbie’s allocation was negotiated, and which she now made explicit:

“Robbie: every module, every pipeline, every runbook must be cloneable-and-runnable by someone who has never met you. The repo is the platform’s memory, not yours. If you get hit by the number 14 bus — or, more likely, by a Sydney recruiter — the platform survives you. This is the condition of your allocation.”

Robbie’s response, per the meeting notes, was “harsh but fair.” His counter-condition — a test subscription for platform development and a budget for it — was granted on the spot, which is how negotiations between competent adults are supposed to go.

The Thing That Validated Everything: The Questionnaire Arrives

Halfway through the design arguments, with nothing deployed yet — no management groups, no hub, nothing but a document and a repo — an email landed from the commercial team.

MegaCorp Megalodon’s annual vendor security review had arrived, escalated, with a 40-day response window and a line noting that incomplete responses would affect contract renewal terms. Serge Secure forwarded it to Fakey with a subject line of “You may want to see this before it sees us.”

Here’s the moment worth pausing on. The platform doesn’t exist yet. Under the old way of working, this questionnaire would have consumed Serge and Locksley Keymaster for three weeks of panic-archaeology through the Petone estate, and still shipped with answers like “data is stored securely in our facility” — the kind of answer that makes enterprise procurement people sharpen knives.

Instead, something different happened. Serge opened the Discovery Week artefacts — the requirement register, the control triage, the design decisions document — and found that a large fraction of the questionnaire was already answered, in writing, with reasoning attached.

• Where is customer data stored and processed? — A documented residency decision: personal data in Azure NZ North, non-personal analytics permitted in Australia East, support/telemetry flows under design review. Not yet implemented — but the position existed, with rationale.
• How are security controls selected and mapped to standards? — The ENFORCE/OBSERVE/ENABLE triage against CPS 234 obligations, in a spreadsheet Serge himself had edited.
• How are exceptions to security standards managed? — A register with an SLA, a named risk acceptor, and its first live entry (the fraud corridor, measured and reviewed).
• How is cost and accountability structured? — Not asked, but the subscription strategy memo answered questions MegaCorp hadn’t thought to ask yet.

The response was drafted in four days instead of four weeks. Not because the controls were all in place — they aren’t, and the response says so honestly, with the roadmap attached — but because the organisation could explain itself. The commercial team, who had braced for another six-week silence, sent the following note to Fakey’s team:

“Whatever this document is you’ve given us — we would like more of it. Two other vendors sent us spreadsheets. You sent us reasoning.”

Fakey put that note, verbatim, at the front of the design decisions document. It is now the team’s answer to anyone who asks why the documentation discipline matters:

The requirements document and the design decisions are not overhead on the platform. They are the platform’s first deliverable — and this time, they arrived before the platform did, and they were worth revenue.

The Document Itself: The Structure You Can Steal

The fakey.xyz Design Decisions Document, in its final shape:

1. Purpose — the one-page “what is this platform for” from Part 1, updated with Discovery Week findings. Always first.
2. Decisions — one section each, in a fixed format:
   • The decision, in one sentence, at the top
   • The options considered (including the rejected ones — rejections age well)
   • The argument that settled it, including who raised the deciding constraint
   • “What would have to be true for us to change this” — the trigger condition
   • The named owner
3. Deferred Decisions — explicitly listed as not-yet-decided, each with the date or trigger by which it must be decided (ExpressRoute, single-CI standardisation, DR topology). A visible “we haven’t decided” beats an invisible “we forgot.”
4. Open Questions — from the assumptions list, each with a named falsifier and a review date.
5. Appendix: The Evidence — Discovery Week register, control triage, the MegaCorp note.

Current decision count: 11 decided, 6 deferred, 4 open. The document is 14 pages. Nobody has ever had to read all of it — which is the point. Each person reads the decision they’re affected by, and finds their name in it.

Next in the Series

Part 4 — “Increment One: The First Six Weeks.” Management groups go live, the first policies deploy in audit mode, Tessa Spreadsheet meets Azure Cost Management for the first time, and the team learns what “minimum viable” actually means when your platform team is 1.6 people and your first workload team is already asking for their environment.

What’s the hardest-fought design argument in your landing zone — and did the reasoning get written down, or did it leave with the person who won? Comments open at fakey.xyz.