TechComm Summer Classics give us the chance to highlight some of our most popular and helpful content. First published in September 2013, our popular user guide template helps new and veteran technical communicators build out the most common type of technical content.
Editors Note: This user guide template is one in a series of templates to help readers plan and manage communications and content management activities, resources and deliverables. We welcome ideas and suggestions for other Template Tuesday materials.
The User Guide (aka User Manual) provides the information and instructions needed to set up and use a product. A User Guide includes written and visual information (such as diagrams or screen shots) to assist the user in completing tasks associated with the product (or service), organized along functional or workflow lines.
The User Guide explains how to do something with the product, and often includes the why, and what happens if the task is not done correctly. A well-constructed User Guide provides information geared to the typical user of the product, and provides both procedures and a context for completing the procedures in concise and jargon-free language.
This user guide template is designed to support either a workflow-based or functional approach to the tasks associated with the product. Most technical communicators use this format to document software or hardware. With some tweaking, you can easily use this template to document a whole range of electronic, manufacturing or other hard goods, as well as complex processes or service flows.
Traditional user guides, particularly for software applications, often document every function and option available organized by how the functions were accessed in the user interface. A growing number of technical communicators (technical writers, user assistance specialists, content developers, etc.) subscribe to a user-centered approach to design and documentation, and have begun to move away from exhaustive documentation of every function available. This form of user assistance uses business workflows to organize the information and instructions, so chapters and sections may be organized around performing a set of tasks related to a business role or activity, using the product being documented. In both cases, you should draw on development documentation such as use cases, user stories (Agile) or personas, to determine what features to cover and in what order.
This user guide template includes a set of styles that can support eventual conversion to other formats. It follows the traditional sequential path of a document, rather than the componentized, topic-based style of content creation required for digital media. However, because it’s structured to support either functions or workflows, it can serve as a good starting point for technical communicators who are not yet using CCMS or structured authoring tools.
Using the Template:
- Determine the purpose of the user guide and identify the audience(s).
- Review development documentation around use cases or user stories to determine how to organize the content and the information to include in each chapter and section.
- Sketch out the workflows to be covered.
- Develop an outline of the guide contents
- Download the User Guide Template (Word – .docx) file and save to a local location.
- Customize headers and footers, as well as other styles according to your company’s guidelines.
- Research and develop content and compile it into the template.
- Use the outline to develop a table of contents.
- Consider including a glossary of terms specific to the product (or the industry).
- Depending on length, develop an index.
- Test the guide.
- Revise the content in the guide.
- Produce the final draft, and publish to the delivery format(s) of choice.
- Follow organizational policy and guidelines on document retention to manage draft versions, and subsequent revisions.
- Obtain feedback, evaluate, and revise the content as applicable.
Download: User Guide Template (168 kb – Microsoft Word)
Do you have other user guide templates that work well for the products you are documenting? Are you in an Agile development environment and have tools for creating user assistance that aligns with Sprints? Feel free to contact us and submit your templates. We’ll provide credit to you for assisting the TechWhirl community and contributing to Template Tuesdays.