In Search of the Perfect Template

By Suchitra Govindarajan

What is a template? Well, it depends on whom you ask. If you go by the posts on technical writing mailing lists, a template is the Holy Grail of technical writing. Some seekers seem to believe that all they have to do to write a document is find the right template—fill in the blanks, change the text, and hey presto, the document is written. This article is not about such kinds of templates. While these templates recommend the content that should be in a document, the templates I’m going to talk about work like a presentation style guide.

A good document template is not merely something that looks nice. A lot depends on what lies below the surface.

Templates should take care of these elements, at the least:

• Character and Paragraph Styles

The template should have defined paragraph styles for body text, headings, lists, captions, and text within tables, headers and footers. Styles can also be created for special kinds of information. For example, if the document is a user guide, you may need styles for notes and warnings. To give the writer true flexibility, you should take enough care to see how these styles look when used in juxtaposition. For example, if the writer wants to use a numbered list within a bulleted list, the indentation should line up, and the line spacing should be even. Also consider creating styles that perform more than one function. For example, an indented body text style can be used both as the “explanation” line after a list item, and as the body text after a second-level heading.

Character styles are often overlooked, but they perform the vital function of applying a style to a specific word. The most common character styles are those for italics and bold. You can also have character styles for filenames (usually a fixed-width font) and hyperlinks.

• Paragraph Breaks

A good template should automatically control how paragraphs break over pages. To do this, define the “keep with next” and “keep lines together” options in the appropriate paragraph styles. For example, always define the first item of a list (yes, use a different style for first list items!) with a “keep with next” option, so that at least the first two elements stay together. Do the same for headings, and captions (if they are placed above graphics).

As with other things in life, going overboard and applying these options in all your styles can lead to disastrous results.

• Tables and Graphics

With some software, it may be difficult to define styles for tables and graphics. A good idea is to add a sample of these or the conventions used for these, that the user could copy and re-use. Captions should be set up to renumber automatically.

• Navigation Aids

Navigation aids such as the Table of Contents and the Index can be set up beforehand so that all the writer has to do is update them. This can be a huge timesaver at the deadline, when strange things tend to happen.

• Page Layout

Defining the page layout not only means setting the paper size and margins, but also deciding what appears in the headers and footers, whether that’s the page numbering scheme or the title of the document. Consider using fields, style references, and auto-text features to automatically update such information.

What makes a template effective?

As with software, you can add all kinds of fancy features to your template, and still end up with something that no one uses.

To be truly effective, templates should be:

• Easy to use—The simplest way to find out whether the template is usable is to ask those who use it. The technical writing maxim about knowing your audience applies here as well.

• Comprehensive—Think of a template as having a library of conventions, styles and macros. They should cover most of the common situations that writers will encounter, but also be flexible enough to cover more complex documents.

• Dynamic—A good template is one that is revised periodically, according to the needs of the users, and sometimes of the company. Not only should styles and other elements be changed or added, those that are not being used should also be removed.

• Well-organised—Ensure that your templates, whether one or many, are stored in a central location. Even within the template, take care when naming the styles as many programs list them alphabetically. For example, indented styles, or styles that are subsets of others, should be named so that they appear below the main style.

In the end, a lot will depend on the effort you put in while creating the template. At its best, a template should let you forget about its existence, so you can concentrate on the most important task of all—writing.

(Suchitra Govindarajan works as a Technical Writer for an accounting and business software company in Melbourne, Australia.)

STC India | Home | Contact Us

Copyright © 2003 India Chapter STC. All rights reserved.