User Manual Tutorial Jabbal Singh Gurnish

8/13/2019 User Manual Tutorial Jabbal Singh Gurnish

1/16

IT Support and Documentation Department


2/16

Table of Contents1 Introduction ...............................................................................................................................1

1.1 The use and function of user manuals .......................................................................................... 1

1.2 The process of preparing a user manual ....................................................................................... 1

1.3 General Principles of creating effective User Manual .................................................................. 1

2 Section I: Identifying and Defining Audience and Purpose ............................................................2

2.1 Audience identification ................................................................................................................. 2

2.2 Audience definition ....................................................................................................................... 2

2.2.1 Obsessive Nerds .................................................................................................................... 2

2.2.2 Computer program method .................................................................................................. 2

2.2.3 Handyman ............................................................................................................................. 2

2.2.4 Minion method ..................................................................................................................... 2

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

3 Section II: Writing the User Manual .............................................................................................4

3.1 Front Matter ................................................................................................................................. 4

3.1.1 Cover Page ............................................................................................................................ 4

3.1.2 Table of Contents .................................................................................................................. 4

3.1.3 Preface .................................................................................................................................. 4

3.1.4 Disclaimer .............................................................................................................................. 5

3.1.5 Copyright placement ............................................................................................................. 5

3.2 Body of the Manual ....................................................................................................................... 6

3.2.1 Reference material ................................................................................................................ 6

3.2.2 Guidelines of writing clear and effective procedures ........................................................... 6

3.3 Back Matter ................................................................................................................................... 8

3.3.1 Glossary ................................................................................................................................. 9

3.3.2 Index ...................................................................................................................................... 9

3.3.3 Appendix ............................................................................................................................. 10

4 Section III: Style of the Manual.................................................................................................. 11

4.1 Standards .................................................................................................................................... 11

4.2 Format and Structure .................................................................................................................. 11

4.3 Page design and visuals ............................................................................................................... 12


3/16

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


4/16

User Manual Tutorial

vidiomsystem | Introduction 1

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 atechnical communicationdocument 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

intendedaudience,withtechnical 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.
http://en.wikipedia.org/wiki/Technical_communicationhttp://en.wikipedia.org/wiki/Documenthttp://en.wikipedia.org/wiki/Audiencehttp://en.wikipedia.org/wiki/Jargonhttp://en.wikipedia.org/wiki/Jargonhttp://en.wikipedia.org/wiki/Audiencehttp://en.wikipedia.org/wiki/Documenthttp://en.wikipedia.org/wiki/Technical_communication


5/16


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

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, andMinion, 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 thenext. 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 methodThis 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.


6/16


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

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 manualthat 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.


7/16


vidiomsystem | Section II: Writing the User Manual 4

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 matterconsists of:

Cover page

Table of contents

Preface

Disclaimer

Copyright placement

3.1.1

Cover PageCover 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


8/16



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
http://www.vidiomsystems.ca/legal_services/disclaimer.htmlhttp://www.vidiomsystems.ca/legal_services/disclaimer.htmlhttp://www.vidiomsystems.ca/legal_services/disclaimer.html


9/16



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 proceduresWriting 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.
http://en.wikipedia.org/wiki/Related_rightshttp://www.vidiomsystems.ca/legal_services/disclaimer.htmlhttp://www.vidiomsystems.ca/legal_services/disclaimer.htmlhttp://en.wikipedia.org/wiki/Related_rights


10/16



An important consideration is identifying the major tasks the procedure you are writing

instructions for. The term procedurerefers to the whole set of activities your instructions are

intended to discuss. A taskis 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.

3.2.2.2 Chunking textChunking 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.

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.

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.


11/16



3.2.2.3 Numbering stepsWhen 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.

3.2.2.4 Using If-Then structureWhen 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.

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

Press ENTER

Or

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

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.

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.


12/16



3.3.1 Glossary

Glossary is an alphabetical list of technicalterms together with theirdefinitions 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.
https://en.wikipedia.org/wiki/Term_%28language%29https://en.wikipedia.org/wiki/Definitionhttps://en.wikipedia.org/wiki/Definitionhttps://en.wikipedia.org/wiki/Term_%28language%29


13/16



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.


14/16


15/16


vidiomsystem | Section III: Style of the Manual 12

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 .pngformat.

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.


16/16


vidiomsystem | Section III: Style of the Manual 13

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.

User Manual Tutorial Jabbal Singh Gurnish

Documents

Transcript of User Manual Tutorial Jabbal Singh Gurnish