Lead Writers: John New, Kieran Morgan | Expert Reviewer/s: Deirdre Wilson

This chapter focuses on the role of templates in technical documentation, distinguishing them as unique technical documents through the use of instructional, placeholder, and sample text. It presents a practical, step-by-step approach to template creation with a focus on maintaining consistency and aligning with organizational branding. The chapter also highlights the role of generative AI in streamlining the template creation process and includes both a sample user guide template and a comprehensive checklist to facilitate effective template design.

Who Should Read This
• Beginner Technical Writers • Career Advancers • Cross-Domain Professionals
Table of Contents: Technical Writing Process
Previous: Chapter 14: Design Stylesheet	Next: Chapter 16: Writing Principles

1. Introduction

Imagine you’re baking a cookie or a cake. You reach for a cookie cutter to shape your dough before baking. This simple tool provides a predefined shape that makes your task easier and the outcome more consistent. Similarly, in technical writing, templates serve as indispensable tools, just like cookie cutters. They offer a pre-established mold or pattern for your documents.¹

Templates are essential tools for all technical writers. They save time by eliminating the need to design and create a new document from scratch. They also ensure alignment with your organization’s branding and maintain consistency across writers. A well-designed template allows you to focus on content development rather than on formatting and design, speeding up the writing process. Additionally, templates guide writers toward uniformity by offering a consistent structure with predefined elements and placeholder text, which helps to facilitate a standardized layout and language across the organization.

This chapter guides you through the process of creating a template from scratch. It explains how templates are structured into three main elements: instructional text, placeholder text, and sample text. These unique elements constitute the “meta-information” layer, which distinguishes templates from all other document types. We will then discuss the distinction between forms and templates, and explain some of the common elements expected in templates.

Finally, we offer practical steps to guide you through the process of template creation, together with a handy Template Design Checklist.

Insight

Check Before You Create For technical writers in mature organizations, starting a document without a template is rare. If you’ve been asked to write a document and no suitable template exists, make sure you double-check before creating one from scratch. If there really is none, it’s a prudent step to create one in case a similar document type is needed in the future.

2. [Theory] Forms vs. Templates

When you’re designing templates, it’s important to understand the distinction between forms and templates, as they serve different purposes:

• Forms (information gathering): Forms are designed to collect data or information. They are often interactive and designed to be user-friendly, guiding the user to provide specific types of information. Forms can be physical or digital, like interactive webpages or even Adobe PDFs, and are important in situations where structured data collection is essential. They are particularly useful in gathering data and ensuring that the information collected is organized and consistent.
• Templates (cookie cutters for information): Templates are pre-structured documents used to maintain consistency and efficiency in document creation. They serve as a framework for presenting information, ensuring that all documents adhere to a specific format, style, and structure. Templates often include instructional text, placeholders, and sample text to guide the user in creating the final document. They are essential for branding, ensuring consistency across documents, and saving time and effort in document creation.

What Does That Mean?

Forms Interactive tools designed for structured data collection, guiding users in providing specific information. Forms can be physical or digital, and are important for organizing data input in an efficient and consistent manner. Templates Pre-designed frameworks for documents, providing standardized layouts and styles to ensure consistency and efficiency in writing while aligning with an organization’s branding and visual identity.

3. [Theory] Metainformation, the Unique Characteristic of Templates

Templates are just like any other technical document—with one very important difference. Templates have a unique set of characteristics that turn them from “cookies” into “cookie cutters.” This is what we call the metainformation layer. It’s what makes templates a class of document all on their own.

The metainformation layer consists of three elements:

1. Instructions: Instructions guide users in the proper and consistent use of the template. They are there as a temporary signpost to guide the template creation.
   1. How to identify: Instructions are typically placed on a clearly marked cover sheet or textbox at the front of a template so they can be deleted prior to publication.
2. Placeholder text: Placeholder text acts as a prewritten script for content within the document. It guides users toward consistency of language, where a premium is placed on consistency rather than creativity.
   1. How to identify: Placeholder text is usually differentiated from other text by the use of [square brackets] for variables, a cue for the user to replace them with their own text.
3. Sample text: Sample text goes a step beyond placeholder text to provide an additional layer of guidance. Sample text gives the template user an idealized example of how a section could be worded, often drawing from previous examples considered best practice.
   1. How to identify: Sample text is often identified by italics or a different font color.

What Does That Mean?

Metainformation Metainformation is information about other information. This is a term we’ve used to describe instructions and placeholder text in templates. In doing so, we’ve leaned on the definition of a closely related concept, metadata, which is “data that provides information about other data.”2 If you’re not clear on the difference between data and information, see Chapter 9 Collect Information > 2. [Theory] DIKW Pyramid.

4. [Theory] Common Elements of Templates

In addition to metainformation, a well-designed template includes various elements that contribute to its effectiveness and ease of use. These elements ensure comprehensiveness, consistency in the documents created from the template, and adherence to best practices.

• Style sheets: Defined styles for elements such as headings and paragraphs are essential for maintaining consistency in formatting and appearance, as well as for alignment with branding elements like logos and color schemes. See Chapter 16: Design Stylesheet.
• Document control tables: These are important for maintaining version control and document history. Typically these tables include information on document revisions, authorship, approval dates, and change history.
• Predefined headings: Consistent sections in the templates provide a structured approach that end users expect in the documents.
• Footer and header information: Standardized headers and footers, containing the document title, page numbers, copyright statement, version number, and other relevant information, are important for professional presentation and navigation.
• Tables and charts: Preformatted tables and charts facilitate uniform data representation across various documents.
• Legal and compliance notes: These sections accommodate disclaimers, copyright information, and other legal requirements, ensuring compliance and protection.

5. [Practice] Design Templates

Designing templates is a senior technical writing skill. It involves skillfully orchestrating technical writing theory and practice in concert. In fact, designing a template is a microcosm of the entire technical writing process. The only thing that templates don’t normally require is a comprehensive Documentation Plan—unless they’ll be used by hundreds of users, in which case, perhaps it’s best to consider one.

Here are the steps to create a template, organized by the phases of the technical writing process.

5.1. Step 1: Plan

• Audience analysis: Determine who will use your templates, and consider their skill level and needs. This will guide the template’s usability.
• Obtain guidelines: Obtain your organization’s brand guidelines or other rules concerning the visual layout of documents.
• Collect examples: Gather best-practice document examples to inform your template design. This can include internal documents, such as existing templates, as well as external sources for broader insights.

5.2. Step 2: Design

• Structure development: Create a hierarchy of headings based on common elements found in your best-practice documents. This sets the foundational structure of your template.
• Stylesheet creation: Develop a stylesheet following your organization’s brand guidelines or adapt an existing organizational stylesheet.

5.3. Step 3: Write

• Placeholder text: Write placeholder text under each heading, balancing specificity and generality. Use clear markers like [square brackets] for identification.
• Sample text: Compose sample text that provides practical guidance and examples that are distinctively marked for easy recognition.
• Instructional text: Explain template usage at the front, covering placeholder text identification and deletion. Consider linking to an intranet page for detailed instructions.

5.4. Step 4: Review

• Self review: Evaluate the template using the Template Design Checklist for thoroughness.
• Testing: Test the template on a real use case and seek peer feedback.
• External review: Have your brand and legal teams review the template for compliance and accuracy.

5.5. Step 5: Publish

• Publishing: Secure approval and publish your template. Aim for wide communication about its use, especially if it supersedes an older version. Provide clear guidelines on its usage and whom to contact for inquiries.

Tip

Use Artificial Intelligence to Streamline Template Creation If your organization is okay with you using generative AI, it can save you a lot of time in designing templates. One of the greatest strengths of generative AI is its ability to synthesize existing information, design structure, and write placeholder text—all of which are extremely helpful for template creation. See Chapter 8: Artificial Intelligence (AI) for Technical Writers for more information on how to use AI tools such as ChatGPT.

6. [Template] Technical Document Template

To demonstrate the application of the principles in this chapter, we’ve created a Technical Document Template. It’s a general-purpose template that you can use to create any technical document in Microsoft Word. This template features a minimalist stylesheet specifically tailored for technical documents.

It incorporates the metainformation elements described above in the following ways:

1. Instructional text: Clearly marked instructions are situated at the beginning of the template and within relevant headings. These provide guidance for users on how to use the template and should be deleted prior to publication, as per the guidance in the template.
2. Placeholder text: Placeholder text, marked with [square brackets], indicates to the user where they should insert their own variables into prewritten sentences. This guides users toward uniformity in places where consistency is valued over creativity.
3. Sample text: Our template provides essential placeholder text, such as sample headings in the introduction, as well as standard elements like a document control table and copyright statements. This gives users a concrete example of what’s expected in each section without being too prescriptive.

7. [Template] Template Design Checklist

Use the Template Design Checklist to help design a template for a technical document.

1. Kassa, D. (2015). Document Control: Lifecycle and the Governance Challenge. Unknown Publisher. Kindle Edition, p. 81. ↩︎
2. metadata. (2024). In Merriam-Webster Dictionary. https://www.merriam-webster.com/dictionary/metadata. ↩︎