Templates and Template Theatre

Overview

A practice with no templates produces nothing, because the blank page is the obstacle. A practice with elaborate templates produces documents with nothing in them.

This topic is about getting the first benefit without the second, and the mechanism turns out to be field design rather than discipline.

Why templates work

The friction in writing an architectural document is almost never the writing. It is the prior question: what is this supposed to contain?

A template answers that, which removes the decision that was actually blocking people. Three further effects follow:

Artifacts become comparable. Ten ADRs with the same four fields can be scanned; ten free-form notes cannot.

Omissions become visible. An empty negative consequences field is a visible gap that invites a question. In a free-form document, the same omission is invisible — nothing indicates that something is missing.

The cost of doing it properly drops below the cost of improvising. This is the real mechanism. People do the right thing when it is the path of least resistance, and a good template makes it so.

arc42 is worth knowing here: a structured template for architecture documentation, with a defined section set. Treat it as a menu to take sections from rather than a form to adopt wholesale — at a company with no existing practice most of its sections would be empty, and empty sections teach people that the form is optional.

Smaller than you think, and all mandatory

The two design rules, and the second is the one people resist.

Smaller than you think. A five-field template that is always complete beats a twenty-field one that is half-filled. The half-filled version is worse than useless because a reader cannot tell whether a blank field means “not applicable” or “not thought about”.

Every field mandatory. Optional fields get skipped, and the ones that get skipped are reliably the hard ones — which are the ones carrying the value. If a field is genuinely not always applicable, it does not belong in the template; put it in guidance instead.

Template theatre

Module 1 named framework theatre: producing artifacts without doing the thinking, documents that decide nothing. Templates are its most common vector, because a form can be completed without thought in a way that a blank page cannot.

Four detection signals, all specific:

graph TD
  A["Context section describes<br/>the <b>solution</b><br/>rather than the forces"] --> E["<b>Theatre</b><br/>the form is complete,<br/>the thinking is absent"]
  B["Consequences are<br/>all positive"] --> E
  C["Fields restate<br/>the title"] --> E
  D["No option was<br/>rejected"] --> E

  classDef sig fill:#E8A33D,stroke:#C4832A,stroke-width:2px,color:#ffffff
  classDef bad fill:#D9695B,stroke:#B4483A,stroke-width:2px,color:#ffffff
  class A,B,C,D sig
  class E bad

Four signals, each checkable in seconds by someone reviewing a document. All four are about content that is present but empty of information.

Design around fields that are hard to fake

The countermeasure, and it is a design choice rather than an exhortation.

Some fields can be completed without thinking. Decision can restate the title. Status is a word. A context section can describe the chosen solution in the past tense and look plausible.

Other fields are structurally hard to fake:

• Negative consequences. You cannot invent a plausible downside for a decision you have not examined. Attempts read as generic — “adds some complexity” — which is itself a detection signal.
• Options rejected, with the criterion that killed each. Module 8 established why this carries credibility. It also cannot be filled without having considered alternatives.
• The condition that would reverse this. Requires knowing what the decision depends on.

A template built around those three resists theatre, because completing it honestly requires the thinking the template exists to prompt. That is the whole trick: make the hard-to-fake fields mandatory and few, and the form becomes a thinking aid rather than a ritual.

When the template does not fit

Occasionally a decision genuinely does not fit the form. The right response is a note explaining the deviation rather than distorting the decision to fit, or — worse — not recording it at all because the form felt wrong.

A practice that forces every decision through an ill-fitting shape trains people to avoid the practice. One deviation with a sentence of explanation costs nothing and keeps the set honest.

Five fields, two of them hard to fake

The template to introduce, deliberately short.

ADR template — five mandatory fields:

1. Context. The forces, constraints and facts as they are now. What is true that makes this decision necessary.
2. Decision. One statement.
3. Status. Proposed, accepted, or superseded by a numbered record.
4. Consequences. Positive and negative, both required. A record with no negative consequences is returned.
5. Reversal condition. What would have to become true for this to be revisited.

Fields 4 and 5 are the hard-to-fake pair, and they are the reason this template is worth having rather than any template being worth having. Module 7’s work produced a real example of field 5 earning its place: the decision to reject fine-tuning carries the condition that would reopen it — a narrow, high-volume classification task with a measured prompting plateau — which is what stops it being proposed again from scratch.

The proposal template — six fields: the problem in business terms, the options, the recommendation, what is being asked for, by when, and who decides. The last two are mandatory because a proposal without them gets postponed rather than decided.

What is deliberately not in either template: a risk register, a stakeholder list, a compliance section, a diagram requirement. Each is sometimes useful and none is always useful, so each lives in guidance rather than as a field. An optional field is a skipped field.

And the arc42 decision. Not adopted wholesale. Three of its section ideas are borrowed for the HLD — context and scope, building-block view, and constraints — and the rest is left on the shelf. At 140 engineers with no existing practice, a full arc42 document would be mostly empty, and Module 8’s size argument says an artifact that is mostly empty teaches people the form does not matter.

Feeds the workbook

Your process proposal should include the templates you would introduce, kept deliberately short, with the hard-to-fake fields identified. The rubric’s deferral requirement applies here too: say which fields and which templates you are not introducing.

Check your understanding

1. Take a template you have used. Which fields could be completed without thinking? What would you cut?
2. Design a hard-to-fake field for a decision type in your own work. What does completing it honestly require?
3. A decision does not fit your template. What do you do, and what does the alternative train people to do?

---

→ That closes the artifacts. They have to be produced by somebody, and the best ones are not produced alone. — Collaborative design