User Guides Online Tutorial

User Guide A user guide, also commonly known as a manual, is a technical communication document intended to give assistance to people using a particular system. They are written by a technical writer. User guides are most commonly associated with electronic goods, computer hardware and software. Most user guides contain both a written guide and the associated images. In the case of computer applications it is usual to include screenshots of how the program should look, and hardware manuals often include clear, simplified diagrams. The language is written to match up with the intended audience with jargon kept to a minimum or explained thoroughly. Contents The usual sections of a user manual often include: A preface, containing details of related documents and information on how to best use the user guide A contents page A guide on how to use at least the main functions of the system A troubleshooting section detailing possible errors or problems that may occur along with how to fix them A FAQ (Frequently Asked Questions) Where to find further help and contact details A glossary and, for larger documents, an index

What is a User Guide? User Guides are written to explain in layman’s terms how to use software. Generally they accompany other documentation, such as System Administration guides and other related material. They are generally the first ‘port of call’ when something needs to be read. People read them in a hurry, usually when they are frustrated and losing patience with the software. It’s important to keep this fact in mind when you write your guides.

As the name implies, User Guides are written for Users to help them understand an application or system. When writing a User Guide, use simple language with short sentences. This style helps the user through the application. User Guides are often written for non-technical individuals. The level of content and terminology will differ considerably from for example a System Administration Guide, which is very detailed and complex. This rest of article discusses the basic guidelines and requirements to produce a User Guide, such as: • • • • Identifying your audience Writing sections Production standards Other types of documentation.

Identifying Your Audience As with all types of writing, keep your readers in mind. • • • • How will they use the information? Will they install the software by themselves? What level of detail is required? Will graphics help illustrate the procedures

Before You Start Identify the target audience, their level of technical knowledge, and how they will use the guide. Audience Definitions • • • • • • • Procedures Reference Materials Format Technical Language Addressing the User Presentation Conventions Physical Appearance and Requirements

Audience Definitions In the planning process, develop an audience definition that identifies: • • • The user The system The tasks

Software is used to do specific things. Users want to know what the software can do for them, for example, how to print a page in landscape. They are generally not interested in the nitty-gritty technical details – they want to click a button and get a result. That’s it! The User Guide is to teach them how the software helps them to so something. Depending on the guide in question, you may need to address several audiences. For example: • • • Programmers who will troubleshoot the program IT Managers who want to know the resources the program requires Project Managers who want to confirm that the original requirements were met.

If you are writing for more than one audience, develop an audience definition for each one. Examine the definitions and see if you can address all audience types with one document. In many situations, you may need to write a number of documents, of which the users guide is only one. • • When planning, use the audience definition to focus your decisions. When writing, the audience definition serves as a guide for the documentation team and as a benchmark for evaluating the results.

Writing the Parts of a User's Guide The following section describes special considerations for the front matter, body, and back matter of the guide. Front Matter Include a cover page, table of contents and maybe a preface. Cover and Title Page If the document is copyrighted, include a copyright notice Copyright © 2003 The Name Of Your Company. Place this on the cover (and also the title page). Disclaimer Include a standard disclaimer inside the front cover. Preface Use this section to reference other documents related to the software. It is common practice to include a section on "How to Use This Manual" as an introduction.

Contents Always have a table of contents, and include an index at the end of the document. Body of the Guide In the main body, distinguish and separate procedures from reference materials. Procedures Procedures help the user perform specific tasks and may include: • • • When, why, and how to perform a task What the screen will show after performing a task Examples of tasks and program operation.

Procedures involve: 1. 2. 3. 4. Listing the major tasks Breaking each major task into subtasks Leading the user through each subtask in a series of steps Using an "if-then" approach in explaining decisions that users can make.

Learning to Chunk Breaking tasks and information into smaller parts is called "chunking." In user guides, information can be divided by menu options and the consequences, i.e. where each choice leads a user. Subject matter and subtasks that need to be performed divide chunks. Each chunk can form a new chapter or section of a manual. Use a consistently structured format for sections. For instance, you could • • • Begin each section with an overview of the activities to perform Describe the input and the output Provide the procedures for accomplishing the tasks.

When writing procedures, number each step. If you only need a few steps, set them apart with white space. When writing the steps, use the imperative form of verbs, for example: Press [ENTER] or Highlight "Yes" and press [ENTER] to verify that your settings are correct.

Using the If-Then Approach When users must make choices, use an if-then approach to provide clear alternatives and consequences: If you choose "Yes," the program will make Outlook your default email client. If you choose "No," it will set Hotmail as your default email client. Use diagrams for complicated procedures. Reference Materials Readers study reference material when they need more information on a particular topic. Reference materials can include: • • • • • • Program options Dictionary of "hot" keys Error messages Troubleshooting tables Commonly asked questions Examples of input and output

Back Matter Glossaries and indexes (normally placed behind the procedures) are two of the most valuable accessories in user's guides. Glossary This is vital when you create new, program-specific terms or when you use common terms in a special way. • • A small glossary can appear at the front before the contents pages A larger complete glossary should appear in the back matter.

Glossary terms should be flagged (by Italics, for instance) the first time they appear in text. Index Any guide longer than 20 pages benefits from an index. Large documents without an index are impossible to use efficiently. Establishing Standards During production, decide on how standards will apply to:

• • •

Format (the physical design of pages) Style (elements affecting readability) Physical appearance and requirements.

Format Some clients may have format preferences. Check this with the client during planning. A good format maps the organization of the guide, using clear signposts to find reference information easily. To achieve this, use the following tactics: • • • Use headings for organizing information. Place page numbers and section titles on every page, either in footers or headers. Use section numbering with restraint. As an alternative to section numbering, divide instructions into manageable segments, based on activities that the reader will perform. Provide new sections on the right-hand pages for each new division. Dual columns can be used effectively by putting headings in the left-hand column and the text in the right-hand column.

Style Use an appropriate style. Decide on the technical level of your language, how you address the user, and conventions that are required. Technical Language 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. Addressing the User When writing procedures, use the active voice (e.g. Click this) and address users directly (write "you" rather than "the user"). When explaining an action, use the "command" form of the verb: "Choose an option from the menu and press [ENTER]." Presentation Conventions You can improve readability by using specific formats to distinguish selected kinds of information.

For example: a key concern in user's guides is to distinguish user input from system responses, or have different levels of warnings for user actions, such as: 1. 2. 3. 4. Incorrect data Threatening to data Threatening to equipment Dangerous to Staff

Distinguish information by: • • • • • • Indenting Columns Graphic boxes Illustrations Type features (bolding, italics, typeface) Or other devices.

Nonverbal devices, such as icons or diagrams, help supplement verbal instructions. Physical Appearance and Requirements Appearance should be determined by the needs of its users. The size of type, binding, and type of paper all affect a guide's usefulness. Special Requirements If the guide is to be used outdoors or on the move, then the type size should be large enough to read rapidly, binding should be spiral so as not to break easily, and use high-quality paper.

How to Improve User Guides User guides can be extremely helpful or almost totally useless! We've all read guides that had us chewing our knuckles in sheer frustration. As many guides are so poorly written, and become such sources of frustration, they've now got a very bad reputation. And based on their previous negative experiences, most people are now reluctant to read user guides and will run a mile rather than suffer through them. There is hope! Technical writers can resolve this by making difficult subjects easier to understand and ensure that the guides assist the user with the task at hand. Well-written documentation should be easy to:

• • •

Read Understand Access

To do this, when you are writing you need to know: • • • • Who is the target audience? What is their level of proficiency? What special requirements are needed? Where will the product be used?

Define each of these during the planning process. Remember to plan and not write ‘on the fly’ to meet deadlines. To achieve this goal, first outline your requirements. Involve experienced technical writers and information designers at the outset as the project will benefit from their experience, especially in areas such as system design and user interface. The role of Technical Writers is to work with users, customer support and the Development Dept. to ensure that the user’s perspective is captured in the final document. Those writers involved from the start will understand the system better, making it easier to plan and write the required documentation. Document Planning Document planning includes designing the structure and form of the material, as documentation may need to be produced for: • • • Online Help Hard copy manuals Quick reference guides

Decide what works best. Experienced writers can recommend and prototype the best solution. Then decide on the most appropriate documentation formats, such as: • • • Reference guides which will have an alphabetical listing of the software features and explanations on how to use them. User Guide with separate chapters addressing how to different user tasks. Online Help with ‘How To’ sections.

Every manual should be written according to the user's level of expertise. Experienced users will search the reference manual, while novices will refer to the ‘How To’ lessons to learn the product.

Make your decisions on style/content in the early stages of product development. This will ensure that both the Documentation and Development teams understand each other. By following these steps, your documentation should be easier to read, access, and understand. Document Planning Checklist Before starting a large documentation project, plan ahead so that all areas related to the final delivery are covered, such as costs, production, resources, dissemination, and archiving. If you overlook this step your project's success could be undermined by failing to anticipate these items. For example: • • • Did you remember that Mary in Production Dept. is on holiday the day before release? Have you got sign-off for printing? How will you deliver the hardcopy reports?

None of these have to do with the main writing tasks, but are essential for the project's overall success, especially if it ties in with other parallel deliverables. The following checklist offers some areas to consider before starting your project. Questions What are the document's objectives? Notes

Who is the target audience?

What previous work was done for them?

What are the proposed start and finish dates?

Who signs-off the final document?

Who will be in the Writing Team? (note any possible schedule conflicts)

What type of publication will be produced?

Publication type(s): • • • • • • • Technical report Procedures Presentation White Papers System Admin Guide User Guide Other __________

What file formats are required? For example: HTML, Word, On-line Help What documents will the client supply? • • Company style guide Company corporate guidelines

What software will be used? (Are new licenses required?) Will different authors share files?

Will the document be published online?

How often will the document be updated?

What is the proposed release process?

How will it be archived?

What graphics will be used?

Who will supply or design the graphics?

Paper publications

How will the document be distributed? (e.g. available by request) What are the duplication costs? (e.g. considerations such as special bindings, color copying costs)

Online publications

What security is required? What are the costs to do this? What are the website related costs?

Sign up to vote on this title
UsefulNot useful