Templates that make good docs the default, not the exception
Every team has one document that is written well and twenty that are written in a hurry. The difference is rarely the writer. It is whether the shape of the document was decided before the writing began.
A template is a set of questions, not a layout
The weakest templates are decorative: a title, some headings, a coloured banner. The strongest are interrogative. An incident report that asks who was affected, when it started and how you knew, gets you a usable report from a stressed engineer at midnight.
Write the headings as the questions the reader will actually have. If a section heading does not correspond to a question somebody will ask, it is probably furniture and can be removed.
Put the metadata in the template
Owner, status, review date, related service, affected teams: these are the fields that make a document findable and maintainable later, and they are the fields that are never added retrospectively. Carrying them in the template means every new page arrives correctly tagged.
This is what converts a folder of documents into something searchable. Filters work on properties, and properties only exist if something put them there at creation time.
Keep the library small and curated
A library of sixty templates has the same effect as no templates at all, because choosing becomes its own task. Most teams need fewer than ten: a decision record, an incident report, a project brief, a runbook, a troubleshooting article, an onboarding plan, a meeting note.
Let anyone propose one, but require that a new template earns its place by replacing an existing pattern rather than sitting alongside it. Retire the ones that stop being used.
Change the template, not the pages behind it
Templates improve as the team learns what was missing. New documents should pick up the improvement, while documents already written stay as their authors left them, because retroactively rewriting a hundred pages to match a new heading order helps nobody.
Where an old page really does need the new structure, that is a review task with an owner and a date, which is the same mechanism you already use to keep pages current.
Written by the DocuRail Team.
Get the next one
One piece a month on documentation practice.
