Cheaper
Templates, and the Ones That Make It Worse
A template with two or three fields makes writing cheaper by removing a decision. A template with eleven sections makes it dearer by adding ten.
What nobody wrote down here, and what it cost
What the deploy order is
Guessed, then corrected
Four lines would have ended it
How the staging database is rebuilt
Asked seven times
The answer was four minutes long every time
two things nobody wrote down · 16 occasions it cost somebody something
Two things, sixteen occasions, and both answers were short.
Where the real question is capacity rather than willingness, track team hours and projects can supply the work-pattern evidence that a documentation discussion otherwise lacks.
The broader workflow can also be checked against guidance from DEV Community.
Pages written with and without a template, on one team that introduced one mid-quarter
Four-line note, no template
6 / 96Six minutes; the shape was obvious because the content was small
Incident write-up, three-field template
22 / 304Twenty-two minutes; the template supplied the three questions worth answering
Decision note, two-field template
9 / 220Nine minutes, and the second field is what stops it being reopened
Page written into an eleven-section corporate template
85 / 48Eighty-five minutes, seven sections marked not applicable, four readings
four documents · 122 minutes written · 668 minutes saved across 46 readings
Four pages, 122 minutes written, 580 minutes saved across 46 readings. The two short templates reduced the cost by removing a decision. The eleven-section one increased it by adding ten, seven of which had no answer. One team's own quarter.
A template is a good idea in a narrow range and a reliable obstacle outside it, and the difference is almost entirely length.
The mechanism is the same in both directions. A template removes the decision about what to put and in what order. If it removes one decision it helps; if it imposes ten it is a form, and nobody fills in a form voluntarily.
What a good template does
It answers the question "what should I say?" before the author has to think about it.
For an incident: what happened, what we did, what we would do differently. Three fields.
For a decision: what we decided, and why. Two fields, and the second is the one that stops the question being reopened in six months.
For a procedure: the steps, plus where it runs, what must be true first, and how you know it worked. Those last three are the omissions that expertise produces, and a template is the cheapest way to catch them.
Why length ruins it
Every section in a template is an obligation. Faced with eleven sections, an author has three options and all of them are bad.
Fill them all in, which takes an hour and a half and produces padding in seven of them.
Mark seven as not applicable, which looks negligent and feels it.
Not start, which is what usually happens and is the fourth row of the panel.
The eleven-section template was almost certainly assembled by somebody sensible from the union of everything anybody had ever wanted. That union is the problem: no single document needs all of it, and requiring it of every document prices every document at the maximum.
The test for a template
Could somebody complete it in the time they were going to spend anyway?
If the answer is yes, it is a template. If it adds half an hour, it is a form, whatever it is called, and it will be used only when somebody is made to.
A second test: how many fields have no answer for a typical case? More than one and it is too long.
Where to put it
In the place where the writing happens, prefilled.
A template that has to be found, copied and pasted is a template with a retrieval step in front of it, and the retrieval step is enough to stop a five-minute task.
The versions that work are structural: a file in the repository that is already there, a channel topic with the three lines in it, a new page that opens with the fields already present.
The three-line version of almost everything
For most teams, the whole template library can be three things, each short enough to remember without looking.
A fact. What is true, and when it was checked.
A decision. What we decided, and why, and what would change it.
A procedure. Where it runs, what must be true first, the steps, how you know it worked, what to do if it fails.
Anything that does not fit one of those is either rarer than it seems or is not really documentation.
What templates cannot do
They cannot make somebody write. A template reduces the cost of writing by some minutes; it does nothing about whether those minutes are available or whose they are, which is the subject of most of this collection.
Teams that introduce a template as their documentation initiative are usually disappointed for this reason. The template was not wrong; it was aimed at a smaller obstacle than the one they had.
The three templates most teams need
Short enough to remember without looking them up, which is the test a template has to pass to be used voluntarily.
| For | Fields |
|---|---|
| A fact | What is true; when it was checked |
| A decision | What we decided; why; what would change it |
| A procedure | Where it runs; what must be true first; the steps; how you know it worked; what to do if it fails |
The procedure template is the longest and every field in it exists to catch an omission that expertise produces. The decision template's second field is the one that stops a settled question being reopened in six months, and it is the field most often dropped.
The honest use
A template is worth introducing when people are already writing and their output is inconsistent or keeps missing the same things.
It is not worth introducing when nobody is writing, because it addresses none of the reasons they are not. In that case the first move is in the sections before this one, and the template can wait until there is something to shape.