Doc Template

Origin & evolution

Templating documents is as old as the office, but software gave several formats canonical templates. The architecture decision record, popularised by Michael Nygard in a 2011 post, fixed a tight skeleton (context, decision, status, consequences) that spread across engineering teams precisely because it was small enough to keep filling in. Product requirement documents converged on a comparable shape: problem, goals, non-goals, requirements, open questions.

Amazon pushed templating into a cultural rule. Around 2004 the company replaced slide decks with narrative memos, the most disciplined being the six-page memo read in silence at the start of a meeting, and the PR-FAQ template for new ideas. The template here was not a convenience; it was a forcing function that made teams write in full sentences and expose the gaps a bullet list would hide.

The live debate is about template rot. A skeleton that captured good thinking when written can ossify into ritual: sections filled to satisfy the format, decisions justified after the fact, a "non-goals" field that always says "none". The current discipline treats a template as a living artefact with an owner, revised when its prompts stop producing real thinking, retired when the document type no longer earns its overhead.

How it works in practice

A platform team standardises on three templates: a PRD, an ADR, and an incident🚨IncidentDevOps & PlatformA production incidentView reference → runbook. Before, every spec looked different and reviewers wasted the first ten minutes hunting for the actual decision. With the ADR template, a new database choice is captured in fifteen minutes under fixed headings, and six months later an engineer debugging a related issue finds the why in the consequences section instead of asking around. The team also catches the rot early: when three PRDs in a row leave "open questions" empty, the template owner adds a prompt asking what would change the team's mind, and the section starts doing work again.

Documentation template vs. its neighbours

• Document is the filled-in instance. A template is the empty mould; a document is what comes out of it. One template stamps many documents, and a document can exist with no template behind it.
• Knowledge base article📓Knowledge Base ArticleContent & KnowledgeA knowledge base articleView reference → is published, external-facing reference for users. A documentation template most often shapes internal documents (specs, decisions, runbooks). The template governs how a team writes for itself; the knowledge base article is how it writes for customers.
• Decision is the choice a templated ADR records. The template is the container, the decision is the content; modelling them apart lets the same decision be referenced from a roadmap🛣️RoadmapProduct SpecificationA strategic plan of features and milestonesView reference → or a retro without dragging the document's structure along.

In the graph

In the Unified Product Graph, a documentation template sits in the content region as a reusable structure. The canonical edges are product_templated_via_documentation_templateProducttemplated viaDocumentation Templatehierarchy, which marks that a product's documents are standardised on a given skeleton, and content_calendar_schedules_documentation_templateContent CalendarschedulesDocumentation Templatehierarchy, which lets a template be slotted into a recurring cadence (the weekly ADR, the per-launch runbook). Keeping the template as its own node, separate from the documents it generates, is what makes template rot detectable: a template that schedules many documents yet none that connect onward to a decision is visibly a form being filled, not a thinking tool being used.