Pure Danger Tech


Technical documentation templates

15 Mar 2006

Had a couple random thoughts about document templates. I have spent a lot of time over the years writing technical docs (specs, test plans, etc) and that includes creating templates, using templates, not using templates, etc.

Virtues of templates:

  1. Help you remember things to think about while writing a doc
  2. Allows an organization to learn by adding stuff to the template that was important but missed in the past
  3. Lets you focus on content rather than style (especially helpful when using something heavyweight like Word)

Dangers of templates:

  1. Writers feel obliged to include all of the sections specified which leads to:
  2. Copying of boilerplate text from the template or other docs
  3. Inclusion of information that is not important for the particular instance of the doc

  4. Writers feel constrained to only include the sections in the template which leads to:
  5. Tunnel vision around the template
  6. Lack of critical and creative thinking about the subject at hand

  7. Can cause a block if writers feel they must complete the template in serial order and don’t know how to complete a section in the middle. In general the order of writing and the order of presentation are rarely the same although the template pushes you to make them the same.

I’m not really pro- or anti- template, just listing some thoughts. I think if you’re aware of the dangers, then the virtues can be quite virtuous. If you are not concerned about the style issue or you’re writing in a low-style environment (wiki, plain text, email) then you can often get the benefits of a template with a checklist instead and avoid many of the dangers.

In all cases, the goal should be clarify and illuminate the subject. A good format makes that easier and a bad format can make it harder but ultimately it’s about the clarity of the thinking.