online help and user's guide documentation standards … · web viewthe help index contains...

ONLINE HELP ANDUSER'S GUIDE

DOCUMENTATIONSTANDARDS

CONFIDENTIAL

P R O J E C T B I G H O R NVersion: Preliminary

CONFIDENTIAL

ONLINE HELP AND USER 'S GUIDE DOCUMENTATION STANDARDS CONFIDENTIAL

PROJECT B IGHORN ISSUE DATE: AUG 4, 1998 VERSION : PRELIMINARY

Table of Contents

Revision Chart.....................................................................................................................................

Introduction.........................................................................................................................................

Requirements For Hard Copy Documentation (Manual).......................................................................

Page Layout....................................................................................................................................

Headings......................................................................................................................................Headers And Footers.......................................................................................................................

Headers........................................................................................................................................Footers.........................................................................................................................................

Procedures......................................................................................................................................

Procedures As Lists......................................................................................................................Branching Procedures...................................................................................................................

Notes, Tips, Warnings.....................................................................................................................

Notes............................................................................................................................................Tips..............................................................................................................................................Warnings......................................................................................................................................

Text Conventions............................................................................................................................

Table Of Contents...........................................................................................................................

Index..............................................................................................................................................

Requirements For Online Help.............................................................................................................

Window Layout..............................................................................................................................

Main Window..............................................................................................................................Secondary Window......................................................................................................................

Headings.........................................................................................................................................

Procedures......................................................................................................................................

Procedure Topic Layout................................................................................................................Procedure Steps............................................................................................................................

Notes, Tips, Warnings.....................................................................................................................

Notes............................................................................................................................................Tips..............................................................................................................................................Warnings......................................................................................................................................

Text Conventions............................................................................................................................

Navigation......................................................................................................................................

Navigation By Instructions...........................................................................................................Navigation By Format And Graphics Conventions........................................................................

Table Of Contents, Index, And Find................................................................................................

COM PANY NAM E , INC . PAGE I I



Approval Signatures.............................................................................................................................

COM PANY NAM E , INC . PAGE I I I



REVISIO N CH ART

Version Description of Version Author Date CompletedPreliminary Second draft incorporating initial

review comments, distributed for final review

Draft Incorporates final comments from Documentation Team.

COM PANY NAM E , INC . PAGE 1



INTRO DUCTIO N

The Document Requirements are the document standards set for Product Name product documentation. They include the hard copy documentation (manual), online Help, and the documentation insert for the Product Name CD.

REQ UIREM ENTS FO R H ARD CO PY DO CUMENTATIO N (M ANUAL)

Product Name manual is created in Adobe FrameMaker. The manual employs the following conventions.

PAGE LAYOUT

The manual has a page layout of one column with a sidehead. The sidehead provides more white space on a page which encourages our audience to read the document. This layout creates shorter lines of text which are easier to comprehend. Putting headings into the sidehead allows readers to skim to find just the information they want.

HEADINGS

The manual contains three levels of headings. Heading 1 resides in the sidehead and is 18 point VAG Rounded Light. Heading 2 also resides in the sidehead and is 14 point VAG Rounded Light. Heading 3 resides in the column immediately above the text it refers to. Heading 3 is 12 point VAG Rounded Thin in font size 12. Additionally there is a run in heading that is 11 point bold AGaramond, and occurs as the first words or sentence in some paragraphs.

Figure 1 illustrates both the sidehead and column layout and the format of the first three levels of headings.




Figure 1. Layout and Heading Formats for User's Guide

Who are Your Customers?

The first step in building your plan is determining who are your best customers. Product Name gives you three options…

Choosing Your Prospects

An profile uses your own customer information to create a picture of the people who buy your products or use your services.

Using the Standard Profile

Using the Standard ProfileWhen you have selected a standard profile, click OK. The Main window appears.

HEADERS AND FOOTERS

HEADERS

The manual has headers on each page after the title page. Headers contain the text of the first heading on a page. The headings display in the header as follows:

Heading 3, if one occurs on the page

Heading 2, if there is no Heading 3 on the page

Heading 1, if there is no Heading 2 on the page

Figure 2. Header Format

Editing a Profile

FOOTERS

The footers on each page of the manual contain the title of the chapter and the page number. The TOC pages are numbered with lowercase Roman numerals and have no chapter title. The numbering restarts with Arabic numerals at 1 on the first page of the first chapter. The page numbering for the Index restarts at 1 (Arabic) and is preceded by the word "Index."


Heading Level 1

Heading Level 2

Heading Level 3



Figure 3. Footer Format

Introduction 3

PROCEDURES

PROCEDURES AS LISTS

Procedures in the manual are written as numbered lists. Each action of a procedure is a separate numbered step. Therefore, there should be no step that contains more than one action. If a section contains a procedure consisting of only one step, that procedure is noted with an arrow bullet.

Each procedure is complete. For instance, the Save procedure is the same for all the modules. However, it is included every place that is appropriate, even if that means repeating the save steps four times in the same chapter.

Figure 4. Procedures as Numbered Lists

Editing an Existing Custom Profile

1. From the Main window, click WHO.2. From the Who dialog box, click Custom.3. Click OK. The Custom Profile dialog box opens, containing

a list of custom profiles.4. Select a custom profile from the list by clicking on it. 5. Click Edit.

BRANCHING PROCEDURES

Procedures which branchthat is, where the users can make a choice to take one of two or more optionsare formatted with a separate heading format which is 11 point bold Garamond and left-aligned in the column (as opposed to the sidehead). The choices in this branched procedure are noted with square bullets. In between each choice is the word "or" in capital letters (OR).




Figure 5. Branched procedure

Make a choice . . .

At this point you may either

use an existing custom profile,

OR

create a new custom profile,

OR

edit an existing custom profile.

NOTES, TIPS, WARNINGS

The manual contains a variety of material that is set off in a format different from the body of the manual. This text is in 9 point VAG Rounded and contained between two ruled lines. Immediately to the left of this text is an illustration.

NOTES

Notes are explanatory material that adds to the explanation of procedures. They are intended to provide information that will enhance the users' understanding, expertise, or ability to use the software effectively. Notes are illustrated with a notepad illustration.

Figure 6. Note Box

Note Note: This is the only place where you can add additional information for prospect lists. We recommend that you add descriptive information about your list and the promotion for which you used this list here.

TIPS

Tips are hints that allow the users to accomplish a task more effectively. Tips are illustrated with a light bulb.




Figure 7. Tip Box

Tip: Check the Example box near the bottom right corner of the Import Customer File Assistant - Name dialog box to see what affect your actions have. Use the up and down arrows to scroll through your customer records.

WARNINGS

Warnings are information that notifies users of effects of actions that are unrecoverable, or that will cause problems using the software in the future. Warnings are illustrated with a bomb.

Figure 8. Warning Box

If you click Cancel, you lose any work you have done to create an automated profile. If you want to save that work, and possibly edit it later, click Finish.

TEXT CONVENTIONS

The manual uses the following usage and text conventions.

Figure 9. Conventions and Examples

Convention Example

Names of profiles are in lower case. automated profile

Names of dialog boxes are in title case (initial capitals). Save Profile dialog box

Names of fields, tabs, buttons, and list choices reflect the standard on the user interface (UI). For the most part, these are in title case.

Click the All button

The term "Main window" uses an uppercase M and a lowercase w. Main window

Names of the buttons on the Main window are in all capitals. WHO

The term "click" is used to indicate the mouse action on a button. "On" is not used after "click" when referring to a button.

Click WHERE

The terms "clear" and "select" are used in conjunction with the instruction "by clicking on it."

Select the zip code by clicking on it.

Procedure steps are written in the imperative, or command, voice ("click this button"). If a choice is indicated, users are instructed that

Click Save when you have




"you may. . ." do or choose something. finished editing your profile.

Whenever a button is indicated, the character designated as the shortcut is underlined, as it appears on the button.

Click OK. The Custom Profile dialog box opens.

The manual is written in the active voice. The Profile Characteristics dialog box opens. The box contains a set of tabs.

TABLE OF CONTENTS

The manual contains a comprehensive table of contents containing heading levels 1 through 3.

Figure 10. Table of Contents Sample

Chapter 1 WhoWho are Your Prospects? .................................................1

Choosing Your Prospects with an Automated Profile? ...............................................1Choosing Your Prospects with a Standard Profile...... 1Choosing Your Prospects with a Custom Profile........ 1

Why and When to Use Standard Profiles ..........................2Why Use a Standard Profile?..................................... 2Why Not Use a Standard Profile?............................... 2

Why and When to Use an Automated Profile.................... 9Why Use an Automated Profile? ............................... 9

What Does Electronic Format Mean? ................ 10How Can I Create an Electronic File If I

Don’t Store My Customer Information Electronically? .................................................. 10

INDEX

The index contains terms used in the text as well as related concepts and synonyms to facilitate users' ability to find what they are looking for.




Figure 11. Index Sample

Aautomated profile, defined 12

Bbest prospects, determining 15

Cchoosing prospects

automated profile 12custom profile 7standard profile 1

custom profile, defined 7

REQ UIREM ENTS FO R O NLINE H ELP

Product Name online help employs the following conventions.

WINDOW LAYOUT

There are two windows defined in Product Name help.

MAIN WINDOW

The main window contains overview information. It is larger, resides close to the middle of the screen, and contains a white text region and a yellow non-scrolling (title) region. The main window is a constant size; that is, it does not change size depending upon the content.

SECONDARY WINDOW

The secondary window contains procedural information. It is smaller than the main window, is located further to the right on the screen, and contains a yellow text region and a white non-scrolling (title) region. The secondary window is auto-sizing; that is, it sizes itself to fit the content of a topic that is displayed in it.




Figure 12. Main and Secondary Help Windows

HEADINGS

The help contains two levels of headings. Heading 1 is the help topic title and only occurs in the top, non-scrolling region. It is 11 point Arial bold. Heading 2 is the subhead used in the body of the help topic. It is 9 point Arial bold.

Heading 1 Looks Like This

Heading 2 Looks Like This

PROCEDURES

PROCEDURE TOPIC LAYOUT

Each procedure begins with a navigation section called Getting There. Subsequent steps in the procedure are grouped under informative subheads, such as When Do I Select How Many Prospects.


Main Help Window

Secondary Help

Window



Procedure topics conclude with one or both of the following sections: More Information and Next Step(s). More Information topics provide additional or supplemental information related to the procedure contained in the procedure topic. Next Step(s) lead the users to the next appropriate action(s) in the software.

PROCEDURE STEPS

Procedures in the help are written as numbered lists. Each action of a procedure is a separate numbered step. Therefore, there should be no step that contains more than one action.

Procedures that consist of one step only are noted by a bullet instead of a number.

A procedure illustrating these conventions is displayed in Figure13.

Figure 13. Procedure Window

NOTES, TIPS, WARNINGS

The help contains material that supplements the procedure or overview. They are identified by the word Note, Tip, or Warning in 9 point Arial bold followed by a colon, then by the text. The entire item is indented 0.15 inches from the left margin.




NOTES

Notes are explanatory material that supplement procedures. They are intended to provide information that will enhance the users' understanding, expertise, or ability to use the software effectively.

TIPS

Tips are hints that allows the users to accomplish a task more effectively.

WARNINGS

Warnings are information that notifies users of effects of actions that are unrecoverable, or that will cause problems using the software in the future.

TEXT CONVENTIONS

The help uses the following usage and text conventions.

Figure 14. Text Conventions for Online Help

Convention Example

Names of profiles are in lower case. automated profile

Names of dialog boxes are in title case (initial capitals). Save Profile dialog box

Names of fields, tabs, buttons, and list choices reflect the standard on the user interface (UI). For the most part, these are in title case.

Click All button

The term "Main window" uses an uppercase M and a lowercase w. Main window

Names of the buttons on the Main window are in all capitals. WHO

The term "click" is used to indicate the mouse action on a button. "On" is not used after "click" when referring to a button.

Click WHERE

The terms "clear" and "select" are used in conjunction with the instruction "by clicking on it."

Select the zip code by clicking on it.

Procedure steps are written in the imperative, or command, voice ("click this button"). If a choice is indicated, the users are instructed that "you may. . ." do or choose something.

Click Save when you have finished editing your profile.




Whenever a button is indicated, the character designated as the shortcut is underlined, as it appears on the button.

Click OK. The Custom Profile dialog box opens.

The help is written in the active voice. The Profile Characteristics dialog box opens. The box contains a set of tabs.

NAVIGATION

Navigation in the help occurs on different levels.

NAVIGATION BY INSTRUCTIONS

Each procedure topic contains a section labeled "Getting There." This section describes how the users can get from the Main window to the specific point in the software addressed by the topic.

The headings "More Information" and "Next Step(s)" are labels indicating where to go for specific information in the help. See Figure 13 for illustrations of these conventions.

NAVIGATION BY FORMAT AND GRAPHICS CONVENTIONS

The "More Information" and "Next Step(s)" sections lead the users to lists of titles preceded by graphics buttons called chiclets. The graphics buttons are a help convention indicating a jump to another help window. Both the graphics buttons and accompanying text are configured as jumps.

The button bar of Product Name help contains a "Back" button. This button jumps the users back to the previous topic viewed in the same window. (For example, if I am in a procedure topic and have already viewed another procedure topic, I can click Back and return to the previous procedure topic.) This button is intended to help prevent users from getting lost in the hypertext world of help.

Within the text of a help topic, users will find words that are green and underlined with a solid or a dotted underline. A green term with a solid underline indicates a jump to another topic in help. Users need to click Back to return to the original topic. A green term with a dotted underline indicates a pop-upa definition topic that appears in a separate small box on top of the current topic and disappears once users click anywhere outside that box. A pop-up topic is illustrated in Figure 15.




Figure 15. Popup Topic

TABLE OF CONTENTS, INDEX, AND FIND

The help contains a comprehensive table of contents containing links to all of the topics except for popups. The help index contains terms used in the text as well as related concepts and synonyms to facilitate the users' ability to find what they are looking for. Additionally, help contains a full-text search feature that allows users to look for all instances of a specific word or phrase in the help. Figures 16 and 17 illustrate the Table of Contents and the Index.


Popup Topic



Figure 16. Online Help Table of Contents

Figure 17. Online Help Index




APPRO VAL SIG NATURES

We, the undersigned, accept this document as a stable work product to be placed under formal change control as described by the Change Control Plan document.

Signed: Date:

Signed: Date:

Signed: Date:

Signed: Date:

Signed: Date:

Signed: Date:

Signed: Date:

Signed: Date:


online help and user's guide documentation standards … · web viewthe help index contains...

Documents