IT Support and Documentation Department

Table of Contents
1 Introduction ...............................................................................................................................1 1.1 1.2 1.3 2 The use and function of user manuals .......................................................................................... 1 The process of preparing a user manual....................................................................................... 1 General Principles of creating effective User Manual .................................................................. 1

Section I: Identifying and Defining Audience and Purpose ............................................................2 2.1 2.2 Audience identification ................................................................................................................. 2 Audience definition ....................................................................................................................... 2 Obsessive Nerds .................................................................................................................... 2 Computer program method .................................................................................................. 2 Handyman ............................................................................................................................. 2 Minion method ..................................................................................................................... 2

2.2.1 2.2.2 2.2.3 2.2.4 2.3 3

Purpose definition......................................................................................................................... 3

Section II: Writing the User Manual .............................................................................................4 3.1 Front Matter ................................................................................................................................. 4 Cover Page ............................................................................................................................ 4 Table of Contents .................................................................................................................. 4 Preface .................................................................................................................................. 4 Disclaimer.............................................................................................................................. 5 Copyright placement ............................................................................................................. 5

3.1.1 3.1.2 3.1.3 3.1.4 3.1.5 3.2

Body of the Manual....................................................................................................................... 6 Reference material................................................................................................................ 6 Guidelines of writing clear and effective procedures ........................................................... 6

3.2.1 3.2.2 3.3

Back Matter................................................................................................................................... 8 Glossary ................................................................................................................................. 9 Index...................................................................................................................................... 9 Appendix ............................................................................................................................. 10

3.3.1 3.3.2 3.3.3 4

Section III: Style of the Manual.................................................................................................. 11 4.1 4.2 4.3 Standards .................................................................................................................................... 11 Format and Structure .................................................................................................................. 11 Page design and visuals............................................................................................................... 12

4.4

Technical language and writing style .......................................................................................... 13

User Manual Tutorial

1 Introduction
The planned tutorial is intended in training the recently hired hardware and software engineers by providing step by step guidelines on how to write standard User Manuals for our product lines.

1.1 The use and function of user manuals

A User Manual is a technical communication document intended to give assistance to a user of a particular product. User Manuals are often written in a language that non-technical individuals can understand.

1.2 The process of preparing a user manual

Preparing a User Manual follows a standard template of sections comprised of: Identifying and Defining Audience and Purpose in the first section, The body of the User Manual in the second section, and The style of the manual in the third section.

The following sections describe what each of these needs to contain. Most User Manuals contain both a written guide and the associated images. The language used is matched to the intended audience, with technical terms kept to a minimum or explained thoroughly.

1.3 General Principles of creating effective User Manual

There are some general principles for creating effective User Manuals, including a quick start guide readily accessible, step-by-step instructions, numbered graphics, trouble-shooting and FAQ sections, a glossary of technical terms and a clearly displayed help-line number.

vidiomsystem | Introduction 1

User Manual Tutorial

2 Section I: Identifying and Defining Audience and Purpose

This section provides a description of the audience, purpose and scope of the User Manual.

2.1 Audience identification

The audience is important because different groups of people have varied levels of understanding about certain topics. This is particularly important when the product targets the international market. Depending on the type of the audience, manual writer must choose relevant terminology and make relevant assumptions about what is obvious and what needs to be explained. If it's necessary to use technical terms, they may need to be defined. Similarly, the use of illustrations should also be dictated by the intended audience's profile, with diagrams or screen shots being chosen to clarify points that are most crucial or difficult to understand.

2.2 Audience definition

There are four main types of audience: Obsessive Nerds, Computer program, Handyman, and Minion, each of them creates a specific requirement in preparing the User Manual. Use the audience definition to focus your decisions. 2.2.1 Obsessive Nerds The readers that fall into this category read the entire instructions in the User Manual from beginning to end before starting the practical phase. They need logical flow and coherency throughout the Manual. 2.2.2 Computer program method People that belong in this category read and perform each step without looking ahead to the next. This type of reader is very common. They need logical numbered steps in short sentences along with big conspicuous graphics. 2.2.3 Handyman Handyman refers to readers who begin the task without reading any instructions and return to them only when difficulties arise. These readers are also very common. Table of contents is crucial for them in addition to troubleshooting and the FAQ sections. The index needs to be written in detail as a very good reference for them. 2.2.4 Minion method This method refers to that type of audience that begin a task without reading the instructions and when difficulties arise hand the project over to somebody else. They require the solutions provided for both computer program and handyman method.

vidiomsystem | Section I: Identifying and Defining Audience and Purpose 2

User Manual Tutorial

2.3 Purpose definition

Defining the audience is only the first step in producing a manual. The writer must also understand the manual's purpose, which impacts to a great extent on how its contents will be presented. For an instructional User Manual, the writer must be able to perform the procedures contained in the manual. Otherwise, there will be inevitable errors in the manual that will defeat its purpose. The User Manual contains all essential information for the user to make full use of the product, such as description of the product functions and capabilities, alternate modes of operations and step-by-step procedures for its access and use. Use graphics where possible when writing the manual.

vidiomsystem | Section I: Identifying and Defining Audience and Purpose 3

User Manual Tutorial

3 Section II: Writing the User Manual

This is the main portion of the manual, where the various functionalities provided by the product are listed in an organized manner, by topic, usually in a hierarchical fashion. 3.1 Front Matter Front matter includes the material that appears at the front of the user manual, before reaching the actual body content. The User Manuals front matter consists of: Cover page Table of contents Preface Disclaimer Copyright placement

3.1.1 Cover Page Cover Page is the very first page of the user manual, also called the title page. It contains the product name, its version number, the word User Manual itself and the companys logo. The design is expected to be as follows, all centered text, one per line: The product name will be located at top of the page in black, 36 font point and Bold Version number in 18 point A key feature in 18 point User Manual itself in 26 font size Logo in color at the bottom of the page

3.1.2 Table of Contents Table of content is basically the headings of sections and subsections together with their page numbers. Write all headings in Bold, Cambria (Headings), the major sections (Heading 1) in 14 point, in dark blue, sub sections (Heading 2) in 13 point, sub-sub-sections (Heading 3) in 12 in italics; both in light blue, entries are left aligned, with the page numbers to the left about an inch. For its online version the table of content will be hyperlinked so that the user is quickly directed to the related page. 3.1.3 Preface This initial portion of the document provides a gentle but precise introduction to what the product is intended to accomplish, and a little bit about how it does that. It also introduces the highlighted tips, identified by alighted bulb and cautions and warnings with ANSI symbols. Make

vidiomsystem | Section II: Writing the User Manual 4

User Manual Tutorial

sure you refer to the correct release number for all software and documents that you refer to. An example preface for the Quartus II software is presented in the box below.

3.1.4 Disclaimer Include a standard disclaimer in the next page after preface that outlines the Terms and Conditions for using this user manual. The legal department provides the writers with a complete disclaimer format that is accessible via companys website: www.vidiomsystems.ca/legal_services/disclaimer.html. We want to have it on page 3 in 12 points in capital letters. 3.1.5 Copyright placement Copyright placement should appear in the next page. It is "the right to copy", but also gives the company the right to be credited for the product, who may financially benefit from it, and other

vidiomsystem | Section II: Writing the User Manual 5

User Manual Tutorial

related rights. The legal department provides the writers with a complete copyright format online at companys website: www.vidiomsystems.ca/legal_services/disclaimer.html

3.2 Body of the Manual

Body of a User Manual is the heart of the guide containing the main information for users guides. It includes writing procedure, chunking text, numbering steps, and using if-then structure. In the main body, separate the procedures (also called instructions) from reference materials. This will help the user navigate their way through the guide faster. 3.2.1 Reference material This section is meant to be consulted every time the user needs to look up a particular functionality of the product with exact details. For a [hardware product] the schematic drawings, data sheets, specification sheets, etc. will be a necessity in order to prepare the user manual. For a [software product] reference materials can include: Program options such as different menus and buttons that are presented to the user Keyboard options, for example, hold Alt+Ctrl and 4 to show the Euro symbol Error messages that may arise when you use the application Troubleshooting tips to resolve these issues Frequently asked questions that the user may have about the software

Elaborate on the selling points of the new product and the upgrade from the previous version. The Reference section is written in the style of the Unix manual pages. 3.2.2 Guidelines of writing clear and effective procedures Providing the user with clear and effective procedures requires a thorough understanding of the procedure, the ability to put yourself in the place of the user who will be using your instructions and the ability to visualize the procedure in great detail as well as to capture audience awareness. It involves particular techniques such as chunking texts, numbering steps and "if-then" approach when explaining decisions that users can make.
3.2.2.1 Writing procedures

Writing procedures involves the following tasks: Identifying the major tasks Separating each major task into subtasks Writing a series of steps that walk the user through each subtask Using an "if-then" approach when explaining decisions that users can make.

vidiomsystem | Section II: Writing the User Manual 6

User Manual Tutorial

An important consideration is identifying the major tasks the procedure you are writing instructions for. The term procedure refers to the whole set of activities your instructions are intended to discuss. A task is a group of actions within the procedure. A good approach is to group similar and related steps of an instruction into phases, and start renumbering the steps at each new phase. Refer to the box below for some examples. For example, setting the clock on a microwave oven is one task in the big overall procedure of operating a microwave oven. A simple procedure like changing the oil in a car contains only one task; there are no semi-independent groupings of activities. A more complex procedure like using a microwave oven contains plenty of such semi-independent tasks: setting the clock; setting the power level; using the timer; cleaning and maintaining the microwave, among others.

3.2.2.2 Chunking text

Chunking is mainly breaking large pieces of information into smaller piece of information. When writing user manuals, separate information for each task and their related consequences meaning show the user the results of each action. Subtasks that need to be performed can be divided into chunks. Each chunk can form a new chapter or section within the guide. The tips and examples are centered at the bottom in a box. Suggest other options there if applicable. Use a consistent format for each section, for instance: Introduce each section with an overview of the task to be performed Describe the inputs and outputs. In other words, what the user must enter into the system and what the system will do as a result Describe the procedures for accomplishing these tasks

The boxes below show examples of how a chunked section should appear in a standard User Manual.

View and download previous purchases: iTunes Store purchases: Go to iTunes, tap More, then tap Purchased. App Store purchases: Go to App Store, tap Updates, then tap Purchased. iBookstore purchases: Go to iBooks, tap Store, then tap Purchased.

vidiomsystem | Section II: Writing the User Manual 7

User Manual Tutorial 3.2.2.3 Numbering steps

When writing procedures, number each step and use the imperative form or active voice of verbs. A numbered set of steps is presented in the example below. In addition, an active voice theme is indicated afterwards.

Accessing Your Voice Mail from another Phone: 1. Dial your wireless phone number. 2. When you hear your voicemail greeting, press the asterisk key on the phone you are using. 3. Enter your password.

Press ENTER Or Click "Yes" and press ENTER to submit your details.

3.2.2.4 Using If-Then structure

When users are allowed to make decisions, use an If-Then approach to show the different result for each decision they make. Use diagrams to illustrate more complicated procedures.

If you choose "Yes," the program will make Firefox your default web browser. If you choose "No," it will set Opera as your default browser.

3.3 Back Matter

Back matter of the User Manual appears at the end of the user manual after the main body, and is consisted of three sub-sections: Glossary Index Appendix

vidiomsystem | Section II: Writing the User Manual 8

User Manual Tutorial

3.3.1 Glossary Glossary is an alphabetical list of technical terms together with their definitions to help the user understand the material. These terms must have been used consistently throughout the User Manual. Highlight glossary terms the first time they appear in text. A short glossary can appear at the front before the table of contents A larger glossary should appear in the back matter

3.3.2 Index An index helps users locate specific items very fast without having to search through the entire document manually. Large documents without an index are impossible to use efficiently.

vidiomsystem | Section II: Writing the User Manual 9

User Manual Tutorial

3.3.3 Appendix Appendix is a collection of supplementary material with detailed descriptions that the writer could not cover in the middle of instructions. It includes the safety instructions, warnings, extra functionality of the product and related statistics and diagrams.

vidiomsystem | Section II: Writing the User Manual 10

User Manual Tutorial

4 Section III: Style of the Manual

In addition to effective instructing, the use of color, the text and fonts used, and the icons and graphics can all either make for an easy experience or can derail the user. Here are the suggestions.

4.1 Standards
The online version of the User Manual must be in .pdf format, written in XML and linked onto the companys website.

4.2 Format and Structure

Use headings to mark off key contents of the information so that readers can find it quickly. Write all headings in Bold, Cambria (Headings), and left aligned. First-level headings (Heading 1) are in 14 point, dark blue sub sections (Heading 2) in 13 point, light blue sub-sub-sections (Heading 3) in 12 points and italics, light blue

vidiomsystem | Section III: Style of the Manual 11

User Manual Tutorial

4.3 Page design and visuals

Starting from the first chapter, each page will include a header and footer. The header, left aligned, displays the name of the product and the footer, right aligned, shows the chapter title. Use visuals in terms of numerous screen captures throughout the manual. Page design and visuals follows these principle instructions: Visuals and graphics should have textual inscriptions beside them. The Graphics should be in .png format. Ensure that font size is adequate (use at least 12 point font). Ensure high text-to-background contrast (black on white is best). Use san-serif fonts.
vidiomsystem | Section III: Style of the Manual 12

User Manual Tutorial

Avoid using multiple font styles. Font weight can be used sparingly to denote importance. Use colour coding consistently. Provide plenty of white space between sections and around images and paragraphs. Provide a section (or margins) for the users to make their own notes. Use consistent layout from page to page. Avoid using saturated blue for text and small detail, and never use blue on a red background.

4.4 Technical language and writing style

Match the level of technical language with the audience`s level of proficiency. Always underestimate the knowledge of your readers rather than overestimate it. Limit technical terms to those the user will encounter. If you must define a large number of terms, use a glossary to supplement definitions in the text.

vidiomsystem | Section III: Style of the Manual 13