When creating online help, many authors just create the project and immediately start writing topics. However, help projects have various support files in addition to topics – templates, skins, style sheets, etc. – and it’s more efficient to create them before starting the actual project. Once you do, you can re-use these files in other projects in order to get a lot of consistency from project to project with very little effort. In this post, I’ll discuss one of these support files, the template.
A template is a master document that contains items to be re-used in multiple topics, such as the headings in a topic or even the wording of some content. For example, if multiple authors create task description topics, each topic’s content will obviously differ but the order in which that content is presented should be the same for each topic – the title, a “Required Materials” section, an “Applicable Date” section, and so on, for example. This seems straightforward; why not just have the authors agree on a design, without bothering with templates?
Ideally, all the authors will write the same types of topics consistently – same headings in the same order, same wording for similar “Notes,” and so on. In reality, each author will soon diverge from any one consistent standard. This inconsistency forces authors to think about the structure, sequence, and wording of each topic, so the writing gets harder. The inconsistency also forces readers to verify their mental model of how the material is presented each time they read a new topic, so reading and comprehension are harder.
Templates can ease this problem. If authors need to create a particular type of topic, they create it not from scratch but instead based on a pre-defined template for the topic type. This provides the structure for the topics automatically. Authors can also attach a style sheet to a template so that any topic created using the template not only has consistent structure but consistent styles as well, also automatically. The result is more consistent content that’s faster and easier for authors to write, easier for readers to read and comprehend, and constitutes the first steps toward structured authoring.
Attributes of Good Templates
Limited to your main information types. Analyze the types of topics you create. You’ll find that a few types make up most of the topics. For example, you may find that concept, task, and reference topics make up 95% of what you write. This means that you only have to create a very small number of templates.
Simple to use and the more intuitive the better. If it’s hard to use, or requires training or instructions, fewer people will use it. Remember that any template is competing with your authoring tool’s File > New option, which is about as simple as you can get.
Self-documenting. Template developers often write instructions explaining how to use a template but the template won’t be used if those instructions get lost. A better approach is to make the instructions part of the template itself. For example, the marker for a topic title might be something like [delete this text and replace it with the title]. For example, in a sample “task” template:
[delete this text and type the title]
[delete this text and type the intro description]
Date of Applicability
[delete this text and type the date]
Required Materials
[delete this text and type the first entry in the materials list]
[delete this text and type the next entry in the materials list]
and so on…
“Sold” as being a benefit to the authors, especially if the authors are low-tech or third-party authors rather than a part of the doc group.
Creating and Using Templates
Templates are easy to create and use. Follow these instructions for three common tools:
In RoboHelp 6
(These instructions may change in RoboHelp 7).
To create:
1. Right-click the Templates folder on the Project tab and select New Topic Template.
2. Name the template, click the Appearance tab to link a style sheet (presumably created earlier) to it, and save it as
To use:
1. Click the New Topic icon and select the template from the Template pulldown on General tab.
In Flare 3.X
To create:
1. Create the topic that you want to use as the template and apply a style sheet to it.
2. In Windows Explorer, create a My Templates folder under the My Documents folder.
3. Create a Content folder under the My Templates folder.
4. Save the topic to be used as the template in the Content folder.
To use:
1. Click the New Topic icon, select My Templates in Template Folders list, and select the desired template.
In Word 2003
To create:
1. Create a new document to be used as the template and apply styles.
2. Save the document as
To use:
1. Select File/New, select On My Computer under Templates in New Document pane, and select the desired template.
Easy…
