ie standards

8/10/2019 IE Standards

1/104

Information Element StandardsNovember 23, 2009

CA Technical Publications

The only controlled versions of QMS documents are online. (4698)


2/104

This documentation and any related computer software help programs (hereinafter referred to as the

"Documentation") are for your informational purposes only and are subject to change or withdrawal by CA at any

time.

This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part,

without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may

not be used or disclosed by you except as may be permitted in a separate confidentiality agreement between you andCA.

Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation,

you may print a reasonable number of copies of the Documentation for internal use by you and your employees in

connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy.

The right to print copies of the Documentation is limited to the period during which the applicable license for such

software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify

in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.

TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION "AS IS" WITHOUT

WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER

OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION,

INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, ORLOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE.

The use of any software product referenced in the Documentation is governed by the applicable license agreement and

is not modified in any way by the terms of this notice.

The manufacturer of this Documentation is CA.

Provided with "Restricted Rights." Use, duplication or disclosure by the United States Government is subject to the

restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section

252.227-7014(b)(3), as applicable, or their successors.

Copyright 2008 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein

belong to their respective companies.


3/104

CA Product References

This document references the following CA products:

UnicenterCA-7

BrightStorStorage Resource Manager (BrightStor SRM)

BrightStorARCserveBackup for Linux

eTrustSiteMinder

UnicenterSoftware Delivery

Contact the Technical Information Program Office

For questions or assistance from the Technical Information Program Office

(TIPO), see Getting Help on thehttp://techinfo.ca.comwebsite.

For questions or corrections to this document, create a CA Unicenter Service

Management request and provide the document code (for PDFs, the document

code is in the lower right corner of the title page; for HTML, it is in the title bar).
http://techinfo.ca.com/http://techinfo.ca.com/http://techinfo.ca.com/http://techinfo.ca.com/http://techinfo.ca.com/


4/104

Change History

11/23/09

Moved the note about one-step procedures out of the Procedure Element

Introduction topic and into a new topicOne-Step Procedures(see

page65).

Removed change history from 2005.

03/20/09

In theProcedure Element Steps and Results(see page63)topic, added

information on OS-specific steps within a procedure. These guidelines

were originally published in a Tech Pubs Bulletin.

01/28/08

In the Command Code Element Syntax topic, changed the word operand

to argument. Operand is an obscure and likely misunderstood term while

argument is simpler and more universally understood.

Reformatted the information in the Procedure Element Steps and Results

topic from a table to body text.

09/10/07

Split the topics in the Optional Atoms chapter to organize the information

in the same way the other elements' chapters are organized.

Expanded the Example Atom topic to include more examples and to

include the item element as a related topic.

Added Optional Atoms to Information Element Types.

Fixed the grammar in the Operating Environment Designation topic.

Fixed the various headings so that they were parallel in construction.

07/23/07

The first portion of this list reflects new or changed standards to the Information

Element Standards published in April 2005.

Added syntax lead-in and parameters (item element) as required content for

code elements.

Removed the period following the word (Optional) in the hostname item

element in the Code Element example. We no longer use a period followingthe word (Optional) when it precedes an item element description.

Added operating environment designation and examples as optional content

for concept elements.

Removed code as an optional element for concept elements.


5/104

Removed principle as an optional element for glossary elements.

Changed the second paragraph in the Paragraph topic of the "Glossary

Elements" chapter to read as follows: Glossary element definitions cannot

contain graphics or expanding definitions links to other glossary terms. Jump

links can be used.

Added the image file as a required graphic element.

Added Name clarifier in item title as optional content for item elements.

Added example, graphic, and operating environment designation as optional

content and removed code as an optional element for message elements.

Added additional required content to the principle element: For an important

principle, mention the consequences or resulting impact if the user does not

heed the warning or message in the principle.

Added example as optional content for procedure elements.

Removed code as an optional element for procedure elements.

Added operating environment designation, glossary definition, and example

as optional content for process elements.

Removed code as an optional element for process elements.

Added process as an optional element for troubleshooting elements.

The following list describes global changes to the Information Element

Standards:

Added jumps to all optionalitems in the Requirements topics of all chapters.

Added the name of the element type before the word Requirements in all

chapters to make reciprocal links usable. Changed all references to definition/glossary element to glossary element.

Renamed all concept topic headings that were previously written as

Examples:XXX Elements toXXX Element Examples to eliminate confusion

over how we write example atoms.

Added a new "Optional Atoms" chapter that includes the following topics:

Added a generically written Operating Environment Designation topic to

link to from the optional Requirements topic for elements that previously

had an Operating Environment Designation topic. Also removed the note

about research being required to determine whether customers prefer

mixed-platform (operating environment) or platform-specific language

references.

Added a generically written Example Atom topic to link from the optional

Requirements topic for elements that previously had an

Example/Example Atom topic.


6/104

The following lists all other changes made (by chapter) to the Information

Element Standardsthat did not alter the standards, but enhanced or clarified

information:

Changes to the "Introduction" chapter:

Reformatted to include an introduction sentence, a miniTOC, and two

topic headings: Definition of Information Elements and Information

Element Types.

Added a note following the table in the Information Element Types topic:

Note: For information about the styles and formatting to use in specific

elements, see the Quick Reference for IE Standardsand theAuthor-it

Style Glossary on http://techpubs.ca.com.

Changes to the "Code Elements" chapter:

Information was organized by command code and reference code.

The Definition topic was rewritten and expanded.

Added Syntax Lead-in topic.

Changed the following in the Syntax topic in the command code section:

Changed UPPERCASE to read All UPPERCASE or all lowercase and

added a note to say the use of all uppercase or all lowercase depends

on which platform you are documenting.

Rewrote the description for mixed case to read as follows: Identifies

abbreviations, if you choose to show them. The uppercase letters are

the minimum abbreviation; lowercase letters are optional. Removed

the note about using lowercase for any command that is not

case-sensitive.

Changed the word italicsto read lowercase italics.

Clarified the square brackets [ ] description to read as follows:

Identifies optional operands. Put brackets around each operand.

Include a space to separate multiple operands.

Clarified the brace { } description to read as follows: Identifies

required operands among multiple operands. Put braces around

each operand. Include a space to separate multiple operands.

The Reference Code Element Requirements section was added.

Information about using other sections in documentation was added.

Examples were organized by command code and reference code.

Added business relevance information to the camping command code

example.

Added an example of how the camping command is used. All code

elements should provide an example of how the command is used.

Removed the CLSB Command example because it did not add value.


7/104

Added code element examples to the Command Code section: cabanner

command, caamsalertcsv command, and /DRCLASS command.

Added code element examples to the Reference Code section: Associate

a User Directory with a Resource Partner and Identify Job Management

Server.

Changes to the "Concept Elements" chapter:

Added additional concept element examples: Enterprise Definition

Language Overview; and a before and after rewrite of a concept element

about Backup Strategies.

Changes to the "Glossary Element" chapter:

Added the following sentence in the Definition topic: These elements are

different from a concept element in that they are succinct and do not

provide details about the business relevance in terms of the application.

Changed the required elements to read Heading (Term) and Paragraph

(Definition) in lieu of Term (Heading) and Definition (Paragraph).

Changes to the "Graphic Elements" chapter:

Changed the note in the Definition topic to read as follows:

Note:This element must be used as an atom in other information

elementsit cannot stand alone.

Changed the required elements to read as follows: Name of the graphic

(file name or topic description associated with the graphic) in lieu of

Heading (the topic title associated with the graphic in the database).

Rewrote the examples of ALT text in the third bullet of the required

elements to comply with Section 508 Guidelines.

Added the following note to the Requirements topic:

Note:For more information about graphics, see the Graphics Standard

on http://techpubs.ca.com. For information about writing effective ALT

text for graphics, see the Section 508 Guidelines.

Provided a different example graphic.

Changes to the "Item Elements" chapter:

Changed the note in the Definition topic to read as follows:

Note:This element must be used as an atom in other information

elementsit cannot stand alone.

Renamed the required elements to Title and Description in lieu of Item

title and Item description.


8/104

Changed the note about omitting punctuation in titles of item elements

and referred the readers to the Usage and Style Standardsfor further

information.

Added two new examples of valid item titles showing a name clarifier:

Status (Windows) and Status (UNIX)

Changed the second paragraph in the Title topic to the following: To

facilitate reuse, do not include the item type (name clarifier) in the title

unless it is needed to differentiate the item from another similarly named

item, or to identify platform-specific items with the same name.

Moved the Name Clarifiers topic following the Title topic.

In the Description topic, added that links or cross-references are not

permitted in item elements, and procedural information is not allowed in

item element descriptions.

Removed the note following the table of information categories and their

descriptions to precede the table and not be formatted as a note. Usebold and follow the category name with a colon to indicate these

categories. You may have other information categories you may want to

use.

Clarified to list each category on a separate line.

Formatted the information categories in the table to be consistent with

how it should be done in item elements.

Rearranged the order in the verbs and when to use them in the table in

the Description topic.

Added additional examples of item elements that had subitems and

categories.

Changes to the "Message Elements" chapter:

Added the following note to the Definition topic.

Note:A message element does not describe how to troubleshoot an

error; therefore, an error message may require a message element and

a troubleshooting element with reciprocal links.

Changed the names of the required elements to the following:

The message heading (message number), the message text, or both

in lieu of the message ID (message number), the message text, or

both.

The "Reason" subheading in lieu of the heading "Reason:"

The "Action" subheading in lieu of the heading "Action:"

Added a third sentence to the Heading topic: If no message number

exists, use the message text.


9/104

Provided an example of a message heading that uses the message text.

Added additional information to the Reason topic: Ensure that your

reason gives a thorough explanation so the user has a clear

understanding of the message. The reason text is always introduced with

the "Reason:" subheading.

Added additional information to the Action topic: Ensure that your action

gives a thorough explanation so the user has a clear understanding of

the action to take. In some cases, you can format the action as an item

element and reuse it, or you can embed a procedure element as the

action (omit the procedure heading).

Added information that the action text is always introduced with the

"Action:" subheading.

Provided an example of a message action that used an embedded

procedure.

Provided an item element description for the variable (predicate_name)that was not in the original example message element.

Added related topics to the example message element.

Changes to the "Principle Elements" chapter:

Changed the formatting of Note and Important to list bullet style.

Added text about the note principle providing information that if

removed does not alter or affect the main topic content.

Added an additional second-level bulleted item: Use notes for external

cross-references (links to other deliverables).

Added the following note to the Definition topic:Note:For more information about using a note element for

cross-referencing external deliverables, see the Navigation Standards.

Clarified the information under the Important bulleted item.

Removed the note about principle elements being specific to the topic

they appear in; they are not normally used in other information

elements.

Changes to the "Procedure Elements" chapter:

Removed the example of a one-step process from the note and made it a

separate paragraph. Also, mentioned that one-step procedures do not

need procedure subheadings.

Rewrote the example and removed the result information from the step

line in the definition column of the Format of Results attribute in the

Steps and Results topic. The result or purpose information must be on a

separate line.


10/104

Added the following sentence to the introduction in the Subheading

topic: Do not use procedure subheadings in one-step procedures.

Revised the Content of Step attribute definition in the Steps and Results

topic to clarify to state the action the user takes. Also, added text about

not including any result content (this is usually stated as the purpose for

the action). Also included an incorrect and correct example procedure

step.

Revised the note in the Structure of Steps attribute to read as follows:

Note:If you have a complex dialog with multiple areas on it that can

cause confusion to the reader, begin the step by instructing the user to

locate a specific area, and follow that with the action to perform in the

area. For example, Locate the Media Configurations section, select the

Always Start check box, and click Apply.

Provided an example of how to write a step with multiple choices in the

definition column of the Steps with Multiple Choices attribute.

Removed information about the content of results from the Format of

Results attribute definition and added another attribute (Content of

Results) to put this information in and provided an example of when you

would not need a result statement.

Removed the information following the topic that showed examples of

appropriate steps and results. The information is clear in the many

procedure examples provided in the Procedure Element Examples topic.

Added a one-step procedure element example.

Changed the note in the example topic Create Custom Layouts in Node

View to an important principle.

Changed the heading Procedure Element Example Before Rewrite to

Example Before Rewrite.

Added an introductory sentence to the Defining Calendars example as

follows: To define a calendar, follow these steps: (This more closely

reflects the way we used to write procedures.)

Changed the heading Procedure Element Rewrite Example 1 to Example

1 After Rewrite.

Added a related topic to the example rewrite Define Calendars.

Changed the heading Procedure Element Rewrite Example 2 to Example

2 After Rewrite.

Changed the example procedure element Define Calendars Example 2

After Rewrite as follows: 3. Complete the fields in the dialog. Following

are descriptions of fields that are not self-explanatory. (This allows us to

leave out item element descriptions for those fields that are

self-explanatory.)


11/104


12/104


13/104

Added a new "Optional Atoms" chapter, which includes the following topics:

A generically written Operating Environment Designation topic to link to

from the optional Requirements topic for elements that previously had

an Operating Environment Designation topic.

A generically written Example Atom topic to link to from the optional

Requirements topic for elements that previously had an

Example/Example Atom topic.

Changes to the "Information Element Checklists" chapter:

Removed all "Comments:" headings following each checklist item

throughout the chapter. They were not being used.

Changed the first bulleted item in Code checklist to read as follows:

Heading is formatted as Command Command_typePurpose/function.

The purpose/function begins with an action verb.

Changed wording in the Concepts checklist to read as follows: "Concept

is explained clearly and completely" in lieu of "Concept is clearly

understood by the end of the element."

Added a Glossary checklist item: A term is not capitalized unless it is a

proper name that is usually capitalized.

Added a Graphics checklist item: A graphic element cannot stand alone.

It must be embedded in another element.

Changed the first bulleted item in the Items checklist to read as follows:

Heading is the name of the field, or the parameter, function, or operand

that is part of a window, dialog, HTML page, or command syntax.

Note:An item element does not use a heading style.

Changed the second bulleted item in the Items checklist to read as

follows:

The heading does not include the type of items, such as a button,

parameter, field, and so on, unless it must differentiate the item from

another similarly named item.

Moved the Principles checklist after the Message checklist to be in

alphabetical order.

Changed the third bulleted item in the Messages checklist to add the

following: If message number exists, message text is specified in the

paragraph that follows the message number. Do not change the case or

text of the message.

Switched the first and second bulleted items in the Principles element

checklist.


14/104

Added three additional checklist items to the Principles checklist:

The term and punctuation in Note: and Important! appear in bold

text.

For a note principle, the content is supplemental; for an importantprinciple the content is critical.

Includes only one paragraph (except for a short list for a note

principle, if needed).

Added one additional checklist item to the Procedures checklist: Steps do

not contain result text. The step should include only the action you take,

for example, Click OK to generate the PDF should be Click OK, followed

by the result (The PDF is created) in a separate paragraph.

Added an additional checklist item to the Navigation section of the

Procedures checklist: Inline links are to critical information only.

Added an additional checklist item to the Navigation section of the

Processes checklist: A list of procedures includes inline links.

Added additional checklist items in the Troubleshooting checklist:

Symptom: This heading precedes the symptom text.

Solution: This heading precedes the solution text.

Removed a Structures checklist item: If the item is a drop-down, the

items in the drop-down list are included as subitems or linked as a jump

to another topic.


15/104


16/104

16 Information Element Standards

Chapter 4: Glossary Elements 43

Definition .......................................................................................43

Glossary Element Requirements .................................................................43

Heading....................................................................................

43

Paragraph ..................................................................................44

Glossary Element Examples .....................................................................44

Chapter 5: Graphic Elements 45

Definition .......................................................................................45

Graphic Element Requirements ..................................................................46

Graphic Element Example .......................................................................47

Chapter 6: Item Elements 49

Definition .......................................................................................49

Item Element Requirements .....................................................................49

Title ........................................................................................50

Name Clarifiers .............................................................................50

Description .................................................................................51

Item Element Examples .........................................................................52

Chapter 7: Message Elements 55

Definition .......................................................................................55

Message Element Requirements .................................................................55

Heading....................................................................................

56

Message Text ...............................................................................56

Reason .....................................................................................56

Action ......................................................................................57

Message Element Example ......................................................................58

Chapter 8: Principle Elements 59

Definition .......................................................................................59

Principle Element Requirements .................................................................60

Principle Element Examples .....................................................................60

Chapter 9: Procedure Elements 61

Definition .......................................................................................61

Procedure Element Requirements ................................................................61

Heading ....................................................................................62

Introduction ................................................................................62


17/104

Contents 17

Procedure Subheading ......................................................................62

Steps and Results ...........................................................................63

Procedure Element Examples ....................................................................66

Create Custom Layouts in Node View........................................................66

Open the File ...............................................................................66

Example Before Rewrite .....................................................................67

Example 1 After Rewrite .....................................................................68

Example 2 After Rewrite .....................................................................68

Chapter 10: Process Elements 71

Definition .......................................................................................71

Process Element Requirements ..................................................................72

Heading ....................................................................................72

Introduction ................................................................................72

Steps .......................................................................................73

Process Element Examples ......................................................................73

How Change Management Works (Verification and Rollout Phases)............................73

How Collector Processes Work ...............................................................75

How to Discover Resources ..................................................................76

How a CA eTrust SiteMinder Web Agent Protects Resources ...................................76

Chapter 11: Related Topics Elements 79

Definition .......................................................................................79

Related Topics Requirements ....................................................................79

Heading....................................................................................

80List of Links .................................................................................80

Related Topics Example .........................................................................80

Chapter 12: Structure Elements 81

Definition .......................................................................................81

Structure Element Requirements ................................................................81

Heading ....................................................................................81

Introduction ................................................................................82

List of Items ................................................................................82

Structure Element Example......................................................................83

Summary Window ...........................................................................83

Chapter 13: Troubleshooting Elements 85

Definition .......................................................................................85

Troubleshooting Element Requirements ..........................................................85


18/104


Heading ....................................................................................86

Symptom ...................................................................................86

Solution ....................................................................................86

Troubleshooting Element Examples ..............................................................87

servernameUnresolved After Running a Script Containing NetGetMap .........................87

Agent Fails to Start..........................................................................87

Chapter 14: Optional Atoms 89

Operating Environment Designation..............................................................89

Operating Environment Designation Atom Definition ..........................................89

Operating Environment Designation Requirements ............................................89

Operating Environment Designation Atom Examples ..........................................90

Example Atom ..................................................................................91

Example Atom Definition ....................................................................91

Example Atom Requirements ................................................................91

Example Atom Examples ....................................................................92

Chapter 15: Information Element Checklists 95

Purpose of Checklists............................................................................95

Code ...........................................................................................96

Concepts .......................................................................................96

Glossary ........................................................................................97

Graphics ........................................................................................97

Items ..........................................................................................97

Messages.......................................................................................

98Principles .......................................................................................98

Procedures .....................................................................................99

Processes ......................................................................................100

Related Topics .................................................................................100

Structures .....................................................................................101

Troubleshooting................................................................................101

Index 103


19/104

Chapter 1: Introduction 19

Chapter 1: Introduction

This document is intended for all members of CA Technical Publications. To

properly follow our structured writing style, all writers must adhere to the

information element standards presented in this document.

This section contains the following topics:

Definition of Information Elements(see page19)

Information Element Types(see page20)

Definition of Information Elements

An information element is the smallest, sensible piece of information you canproduce. It can be a single procedure (all the steps in the procedure Create a

New File), a concept (an explanation of information elements), and so on.

Information elements contain bits of information that are so closely related that

they become useful or understandable only when combined.

The bits of information that make up an information element are called

information atoms. Information atoms cannot stand alone but can be assembled

to create information elements.

You can determine whether any grouping of paragraphs, sentences, or lists

constitutes an information element by answering the following questions:

Are all the atoms of information related to the main point?

Does the combination of the atoms serve a single purpose (describe a

procedure, explain a concept, and so on)?

Can you use a single label to describe all the information?

Does the information apply to a single audience?


20/104

Information Element Types



Each type of information has a particular information element type. These types

have standards to ensure consistency across information in the database. The

following information element types have been defined for use in CA

documentation:

Information

Element

Description

Code(see page23) Defines commands or code syntax and parameters.

Concept(see

page37)

Defines and explains an idea.

Glossary(see

page43)

Defines unique terms used in the product.

Graphics(see

page45)

Provides a visual representation of an idea or process.

Item(see page49) Defines a part of an object, such as a button on a GUI

or a command parameter.

Message(see

page55)

Defines text communications sent by the program and

displayed to the user.

Principle(see

page59)

Defines short, important hints on what should or

should not be done.

Procedure(see

page61)

Defines a series of steps you can perform in a given

product.

Process(see

page71)

Defines and explains a series of events, stages, or

phases.

Related Topics(see

page79)

Links information from one element to another.

Structure(see

page81)

Defines a physical object, such as a GUI, that can be

broken into parts.

Troubleshooting

(see page85)

Identifies troubleshooting or diagnostic information

related to the functioning of the product.

Optional Atoms(seepage89)

Provides ways to describeoperating environmentdesignations(see page89) andexamples(see

page91).


21/104


Chapter 1: Introduction 21

Note:For information about the style and formatting to use in specific elements,

see the Quick Reference for IE Standardsand theAuthor-it Style Glossaryon

http://techpubs.ca.com.


22/104


23/104

Chapter 2: Code Elements 23

Chapter 2: Code Elements


Definition(see page23)

Command Code Element Requirements(see page23)

Reference Code Element Requirements(see page26)

Command Code Element Examples(see page28)

Reference Code Element Examples(see page33)

Definition

A code elementidentifies commands, code syntax, or other textural reference

information that can be broken down into parts. Code elements are similar tostructure elements, except that structure elements describe visual objects,

whereas code elements describe abstract objects such as functions or resource

classes. Code elements typically describe what can be entered at a command line

or interface, or what might exist as part of a configuration file.

Code elements can also provide reference information that might be included in

a Software Development Kit (SDK), for example. API documentation provides

enough information to make changes to the code to meet a particular customer

requirement without exposing the complete source.

For command types of information, follow the requirements for command code

elements. For reference information, follow the requirements for reference code

elements.

More information:

Procedure Element Requirements(see page61)

Process Element Requirements(see page72)


Reference Code Element Requirements(see page26)

Command Code Element Requirements

Code elements for commands always include the following:

Heading

Introduction

Syntax lead-in


24/104



Syntax

Parameters (item elements), if appropriate

Example(see page91)

Code elements for commands may include the following:

Operating environment designation(see page89)

Principle(see page59)

Related topic(see page79)

Heading

The code heading explains the purpose of the code. The heading should

represent the basic syntax of the code followed by the type of code it represents,

an em dash, and a very brief description of what the command does, startingwith a verb.

The following are valid examples of code headings:

"awsadmin CommandControl Agent Technology Services"

"xyz.cnf FileConfigure Traps"

Syntax Lead-in

All command code elements contain a sentence to introduce the syntax.

"This command|code|otherhas the following format:"


25/104



Syntax

The code syntax identifies the syntax for the command, including parameters

and special characters.

Use the following guidelines when entering code syntax:

All UPPERCASE or all lowercase

Identifies control verbs, object identifiers, and arguments that must be

exactly as shown.

Note:Whether you use all uppercase or all lowercase depends on which

platform you are documenting.

MIXed Case

Identifies abbreviations, if you choose to show them. The uppercase letters

are the minimum abbreviation; lowercase letters are optional.

lowercaseitalics

Identifies a value that a user must supply.

[ ]

Identifies optional arguments. Put brackets around each argument. Include a

space to separate multiple arguments.

{}

Identifies required arguments among multiple arguments. Put braces around

each arguments. Include a space to separate multiple arguments.

underline

Identifies default values.

|

Separates alternative arguments (choose one).

...

Indicates that the preceding items or group of items can be repeated.

Parameters

Code parameters define switches or options that can be run with a command or

individual items in code syntax that must be defined separately.

Note:To reuse code parameters, define them as item elements.


26/104

Reference Code Element Requirements



Code elements for reference information always include the following:

Heading

Introduction

Reference code elements may include but are not limited to the following types of

information, depending on what you are trying to describe:

Syntax

Parameters (item elements), if appropriate

lement)

Remarks

Example(see page91)

Related topics(see page79)

Heading

The heading specifies the name of the code element being defined. The heading

should represent the function, resource, or so on, followed by an em dash, and a

very brief description of what the function!resource!other does, starting with a

verb.

For example, the heading could be a C++ function, such as the following:

Sm_PolicyApi_AddUsersToWSFEDResourcePartner() Associate User Directory

Introduction

All code elements must have a short introduction explaining the purpose of the

code segment. For commands, this introduction should focus on why the user

would want to use the command. For other types of code, this introduction may

be more descriptive in nature, explaining the importance of the code.

Introduction

The introduction provides a short description of the purpose and use of the code

element in context.


27/104



Other Sections

The following sections are examples of sections that can be included in your

documentation. Headings for any of these sections should not appear in the table

of contents. In addition, you should introduce each section using a similarformat, such as the following:

"This syntax|function|other has the following format!parameters!other:"

Sections that have information similar to syntax are as follows:

Syntax

Varies depending on the code element being described and the

implementation language. It should provide the format of any coding

requirement.

Because multiple sections can exist in a this type of code element, include

the heading Syntax at the beginning of the section.

Parameters

Defines values that are passed as arguments to a function when the function

is called at run time.

Include the heading Parameters at the beginning of the section.

Note: To reuse parameters, define them as item elements.

Return Values

Provides all of the possible values that can be returned by a function.

Include the heading Return Valuesat the beginning of the section.

Resource Names

Describes the name of a resource class that groups resources of similar types

for the purpose of defining access.

Include the heading Resource Names at the beginning of the section.



28/104

Command Code Element Examples


Attributes

Attributes are characteristics of a resource that uniquely identify the

resource.

Include the heading Attributes at the beginning of the section.


Remarks

Remarks can include any additional semantic information about the code

element, for example, the possible side effects on a parameter after calling

the function.

Include the heading Remarks at the beginning of the section.


The following are valid examples of code elements for commands.

camping CommandPing Message Queuing Server

The camping command checks that the message queuing server is running on

the local computer or a specified host. If you specify a host name, the command

displays the round-trip time in milliseconds for messages traveling between the

local computer and the host. If you do not specify a host name, the command

displays the round-trip time in milliseconds for messages traveling on the local

computer.

This command has the following format:

camping [hostname]

hostname

(Optional) Defines the computer name or IP address of the computer you

want to ping.

Default:Your computer name

Example: Ping Message Queuing Server on Your Computer

This example determines whether the message queuing server is running on the

local computer.

camping


29/104



cabanner CommandConfigure Message Banner

Valid on Windows

Use the cabanner command to configure the banner for messages. Banners helpusers to understand a message.


cabanner [-id id] banner

-id id

(Optional) Defines the message number (id) associated with the banner.

Default: Blank

banner

Defines the banner that appears.Limits:1-250 alphanumeric characters

Example:Reboot System 45

Example: Configure Message Banner

This example displays the banner message "Reboot System 45" when message

number 135 is triggered.

cabanner -id 135 Reboot System 45


30/104



caamsalertcsv CommandCreate a CSV File

The caamsalertcsv command creates a comma-separated value (CSV) file of

archived and purged alert records and their associated history and annotation

records. CSV files can be used to create reports that show, for example, the timeof day when most alerts are generated, which servers cause most alerts, and

which operators resolve alerts.


caamsalertcsv [-b|-a|-p] [-smmm-sd dd-syyyyy] [-emmm-ed dd-eyyyyy] [-o

output_file] [-v]

-b|-a|-p

(Optional) Specifies whether to add archived alerts, purged alerts, or both to

the CSV file. Options include the following:

-bIncludes both archived and purged alert records. This is the default.

-a

Includes only archived alert records.

-p

Includes only purged alert records.

-sm mm-sd dd -sy yyyy

(Optional) Specifies alerts that were archived, purged, or both on and after a

specified month (mm), day (dd), or year (yyyy). The default is all alerts

regardless of date. This parameter includes the following:

-sm mm

Includes files created this month (mm) and later.

Limits:01-12

-sd dd

Includes files created on and after this day (dd) of the month.

Limits:01-31

-sy yyyy

Includes files created this year (yyyy) and later.

Limits:1901 and greater


31/104



-em mm -ed dd -ey yyyy

(Optional) Specifies alerts that were archived, purged, or both on and before

a specified month (mm), day (dd), or year (yyyy). The default is all alerts


-em mm

Includes files created this month (mm) and previously.

Limits:01-12

-ed dd

Includes files created on and before this day (dd) of the month.

Limits:01-31

-ey yyyy

Includes files created this year (yyyy) and previously.


-o output_file

(Optional) Specifies the CSV file name (output_file). Surround the name with

quotation marks if the name has a space in it.

Default:Today's date in the format yyyymmdd.csv.

Example:20060213.csv for a file created February 13, 2006

-v

(Optional) Displays the name of the CSV file created, as specified by the -o

parameter.

Examples: Create a CSV File

This example creates a CSV file of all archived and purged alerts regardless

of date and displays the file name:

caamsalertcsv -v

This example copies archived alerts to a CSV file named archived.dat in the

C:\Alert Reports directory:

caamsalertcsv -a -o "c:\Alert Reports\archived.dat"

This example copies alerts purged on April 1, 2005, and later to a file named

from_April.csv in the C:\temp directory, and displays the file name:

caamsalertcsv -p -sm 04 -sd 01 -sy 2005 -o c:\temp\from_April.csv -v

This example copies alerts archived and purged during June 2005 to the file

June.csv in the directory that appears in the command prompt:

caamsalertcsv -sm 06 -sd 01 -sy 2005 -em 06 -ed 30 -ey 2005 -o June.csv


32/104



/DRCLASS CommandAdd or Delete a Disaster Recovery Class

The /DRCLASS command adds or deletes a disaster recovery class from the list of

active disaster recovery classes. It is important that your list of active disaster

recovery classes is current so you can access it quickly in an emergency. Disasterrecovery classes have no impact on Unicenter CA-7 processing unless Unicenter

CA-7 is running in disaster recovery mode.

Changes to the active disaster recovery class list are not saved across restarts of

Unicenter CA-7. To make a disaster recovery class active when Unicenter CA-7

starts, add the class to the DRCLASS initialization file statement.

Use /DISPLAY,ST=DR to display the list of active disaster recovery classes.


/DRCLASS, CLASS=(xx1,...,xx8) [, ACT=ADD|DEL]

CLASS=(xx1,...,xx8)

Defines one to eight disaster recovery classes to be added to or deleted from

the list of active disaster recovery classes. Each disaster recovery class can

be from one to eight characters long. The disaster recovery classes must be

separated by commas and enclosed in parentheses. If a single disaster

recovery class is specified, the parentheses can be omitted.

ACT=ADD|DEL

(Optional) Specifies what action should be performed on the disaster

recovery classes specified on the CLASS keyword.

ADD

Adds the classes to the list of active disaster recovery classes. This is the

default.

DEL

Deletes the classes from the list of active disaster recovery classes.

Examples: Add or Delete a Disaster Recovery Class

This example adds the tier 1 class to the list of active disaster recovery

classes:

/DRCLASS, CLASS=TIER1

This example adds tier 2 and tier 3 classes to the list of active disaster

recovery classes:

/DRCLASS, CLASS=(TIER2,TIER3)

This example deletes the tier 3 class from the list of active disaster recovery

classes:

/DRCLASS, CLASS=TIER3, ACT=DEL


33/104

Reference Code Element Examples



The following are valid examples of reference code elements.

Sm_PolicyApi_AddUsersToWSFEDResourcePartner()Associate a User Directory

with a Resource Partner

This function specifies a group of users that can be granted access to resources

at a particular WS-Federation Resource Partner.

Syntax

This function has the following format:

int SM_EXTERN Sm_PolicyApi_AddUsersToWSFEDResourcePartner (

void* pSessionHandle,

const char * pszProviderOid,

Sm_PolicyApi_User_t *pStructUsers,

int iPolicyFlags

);

Parameters

This function has the following parameters.

Note:In this example, [in] is a C++ standard denotation that the function is

expecting a valid value for this parameter when the function is called. Parameter

values that change during the course of function execution are marked [out]. A

parameter can be both, that is, [in, out].

pSessionHandle

[in] Indicates a pointer to an internal Policy Management API data structure.

The structure holds information about the administrator session and the

client session.

pszProviderOid

[in] Indicates a null-terminated string containing the object identifier of an

existing WS-Federation Resource Partner.

pStructUsers

[in] Indicates a pointer to a Sm_PolicyApi_User_t structure containing

information about the user directory.

iPolicyFlags

[in] Indicates whether the policy created for WS-Federation Resource

Partner includes or excludes a user and whether the policy should be applied

recursively.


34/104



Return Values

This function returns the following values:

Sm_PolicyApi_Success

Indicates the user directory was added successfully.

Sm_PolicyApi_Failure

Indicates the user directory was not added successfully.

Sm_PolicyApi_InvalidHandle

Indicates there was no valid initialization prior to this call.

Sm_PolicyApi_NoSession

Indicates there is no valid administrator session.

Sm_PolicyApi_NoPrivilege

Indicates the administrator does not have the privilege to add a user.

Sm_PolicyApi_InvalidOid

Indicates the Resource Partner OID was not found.

Sm_PolicyApi_DuplicateEntry

Indicates the user is already part of the Resource Partner.

ServerAccess Resource ClassIdentify Job Management Server

The ServerAccess resource class identifies the job management servers that a

user can access. Each Unicenter WCC component allows access only to applicableservers that the current user is permitted to access.

Resource Name Value

The resource name value corresponds to the name specified for the server in the

Unicenter WCC configuration.

This resource name value has the following format:

server/serverName [component] [type]

serverName

Names the server as defined in the Unicenter WCC configuration.

component

(Optional) Names the component issuing the authorization check.

type

(Optional) Names the resources, that is, AutoSys, CA7, or Event.


35/104



Action

Access is the only available action.

Example: Identify myautosys as the Job Management Server

This example identifies the server resource value as myautosys.

server/myautosys


36/104


37/104

Chapter 3: Concept Elements 37

Chapter 3: Concept Elements



Concept Element Requirements(see page37)

Concept Element Examples(see page38)

Definition

A concept elementexplains and defines an idea. Concepts often create a domain

knowledge basis for the user to use the tool, such as an explanation of SNMP for

users who need to use an interface that reads SNMP messages.

Concept elements can be used to describe system requirements.

More information:

Troubleshooting Element Requirements(see page85)

Concept Element Requirements

Concept elements always include the following:

Heading

Explanation

Concept elements may include the following:

Example(see page91)

Glossary definition(see page43)

Graphic(see page45)





38/104

Concept Element Examples


Heading

The concept heading should be a noun form that briefly describes what the

concept explains. Avoid using gerunds if possible. The following are valid

examples of concept headings:

"Concept Elements"

"SNMP"

"Version Identifiers" (not "Identifying Versions")

Explanation

All concept elements must have at least one concise paragraph explaining the

concept. The explanation can include bulleted lists, definitions, graphics, ortables to provide clarity. Concept elements should not include numbered lists or

process steps.


The following are valid samples of a concept element.

Folder Metrics

Folder metrics organize metrics into a tree structure. A folder metric may have

associated properties and methods to enable import of external data, but doesnot have its own associated collected data. If the folder metric is used to enable

and control external data import, additional metric field properties are available.


39/104


40/104



Example Before Rewrite

The following is a sample concept element before applying the concept element

standard.

Backup Strategies

The option supports the following types of backup:

Full backupsStores everything, regardless of when the data last changed.

Full backups store all of your data at once. They produce a complete,

coherent image of the data as it was at the time of the backup. They also

store the backed-up data together in a single, easily managed storage

object. As a result, backup strategies that rely exclusively on full backups are

usually inefficient because the relative percentage of new data in the overall

data set is generally small. Full backups save too many files already

adequately backed up by a previous storage operation.

Incremental backupsStores files that have changed since the last

backup of any type.

Incremental backups let you avoid network congestion and excessive media

consumption. It fits your existing hardware and bandwidth constraints and

fits better with your users' working hours, thereby providing flexibility.

Incremental backups are faster than full backups. If you do several

incremental backups between full backups, many files are still backed up

more than once. This redundancy lets you restore data quickly because all of

the data you need for a full recover is stored in, at most, two data sets (the

full and the last incremental backup). If you select the incremental method,

you must provide a base job ID. The backup will be based on this job ID. If

the job ID is abnormal, or some related backup project cannot be found fromthis job ID, the project will still be backed up with the full method.


41/104


42/104



Incremental Backups

An incremental backup backs up and stores only files that contain changes.

The following list describes an incremental backup in more detail:

Stores files that have changed since the last backup of any type

Bases the backup on a base job ID that you provide

Backs up only the changed data for the selected project or template as an

incremental backup object

Performs a full backup on a project if the job ID you select is abnormal or a

related backup project cannot be found based on the job ID that you provide.

More information:

Backup Strategies (see page 27)

Full Backups (see page 27)


43/104

Chapter 4: Glossary Elements 43

Chapter 4: Glossary Elements



Glossary Element Requirements(see page43)

Glossary Element Examples(see page44)

Definition

A glossary element defines unique terms used in the product that a user may not

fully understand. These elements are different from a concept element in that

they are succinct and do not provide details about the business relevance in

terms of the application.

Note:To facilitate reuse of topics, the definition must be a single paragraph with

no additional paragraph-level formatting and no graphics.

More information:



Glossary Element Requirements

Glossary elements always include the following:

Heading (Term)

Paragraph (Definition)

Heading

The glossary element heading must state the term being defined. The term

should not be capitalized unless it is a proper name that is usually capitalized. If

the term includes an abbreviation, the abbreviation must follow the term in

parentheses. The following are valid examples of glossary headings:

"computer-aided design (CAD)"

"database"


44/104


45/104


Chapter 5: Graphic Elements



Graphic Element Requirements(see page46)

Graphic Element Example(see page47)

Definition

A graphic elementis an illustration, flowchart, equation, icon, and so on. Screen

captures are the most common type of graphic element in our documentation.

Note:This element must be used as an atom in other information elementsitcannot stand alone.

More information:


Item Element Requirements(see page49)

Message Element Requirements(see page55)



Structure Element Requirements(see page81)



46/104


47/104

Graphic Element Example


Graphic Element Example


48/104


49/104


Chapter 6: Item Elements




Item Element Examples(see page52)

Definition

An item elementdescribes a visual object, such as a part of a GUI or individual

parameters in code.

Note:This element must be used as an atom in other information elementsitcannot stand alone.

More information:




Item Element Requirements

Item elements always include the following:

Title

Description

Item elements may include the following:

Example(see page91)

Graphic(see page45)

Name clarifier in item title(see page50)




50/104



Title

Item element titles specify the item label as it appears on the user interface or in

the code. Optionally, the item label can include an item type such as "button,"

"parameter," "icon," and so on.

To facilitate reuse, do not include the item type (name clarifier) in the title unless

it is needed to differentiate the item from another similarly named item, or to

identify platform-specific items with the same name.

Note:For information about using punctuation following fields, see the Usage

and Style Standards.Work with development to eliminate punctuation marks

from the user interface.

The following examples are valid item titles:

"Status (Windows)"

"Status (UNIX)"

"OK"

"Auto-Refresh"

"File Names column"

"Start parameter"

Name Clarifiers

If necessary, specify the field or user interface (UI) item type in the item title.

However, realize that including this information might limit your ability to reuse

these topics. Use the Standard User Interface Glossary for Productsto determine

the appropriate type. Some approved UI item types include the following:

Check box

Option button

Drop-down list

More information:



51/104



Description

A description always follows the item title and explains the function or purpose of

the item. The description must begin with a verb indicating what the item does

(not what the user does to the item) and is as comprehensive as possible, givingthe user enough information to make informed decisions about how to use the

item effectively.

Links or cross-references are not permitted in item elements. Do not put

procedural information in item element descriptions.

Most item elements describe one of the following types of items:

User interface components (such as fields, buttons, table columns)

Code parameters

After the general description text, include as many of the following informationcategories as possible. List each on a separate line and add them in the same

order as they appear in the following table.

Use bold and follow the category name with a colon to indicate these categories.

If necessary, you can use other information categories such as Module.

Information

Category

Description

Default: Indicates the default value for the item type or

parameter.

Limits: Describes any limitations on the field values, such asthe total number of characters allowed, type of

characters allowed, or an acceptable value range.

Example: Provides an example of how the user can use the

field or command option.


52/104

Item Element Examples


Use an active verb to describe the action the item will initiate, such as "Stops" or

"Starts." When the action is unclear, use the following guidelines to determine

which active verb to use:

Verb When To Use

Defines Configurable fields that must be filled in, such as user name or

domain.

Specifies Configurable fields that provide a choice, such as a list of

possible states.

Displays Non-configurable fields that provide visual information, such as

graphs or icons.

Identifies Non-configurable fields that provide textual information that is

not status related, such as program name or version.

Indicates Non-configurable fields that provide textual information that isstatus related, such as UP or WARNING.


The following are valid examples of item elements:

ETC

Identifies the Estimated Time to Complete (ETC) value for a specific task on

your timesheet. At the beginning of the week, the ETC field shows the

remaining work that is estimated for each task. As you enter time in your

timesheet, the ETC value is reduced.

Example: At the beginning of the week, your first task has an ETC of 25

hours. You entered a total of 10 hours worked on that task, so the ETC is

recalculated to 15 hours.

Note: You can edit ETC at any time, but if you adjust the hours for a selected

task, the ETC value is readjusted according to its original value. Therefore,

adjust the ETC value only after you have entered all of your time for the

current timesheet.

day_of_the_week

Records the daily number of hours you worked on a task. For each task on

your timesheet, a grid of fields exists for each day of the week (for example,Sun, Mon, Tue, and so on).

Limits: Two decimal places


53/104



Notes

Provides an area where you can record any noteworthy information about

your weekly tasks. This information is not reported to anyone, but anyone

(such as managers) who can view your timesheet can read your notes or

leave notes for you. When the timesheet is posted, the notes are saved in the

database along with your other timesheet data.

Limits: 255 alphanumeric characters

Save

Saves your timesheet changes in the database. Saving your timesheet

commits the information to the database, making it ready for the

administrator to post.

Note: Ensure all timesheet edits are added to the timesheet before the

administrator's scheduled posting date, because no further edits can be

added after posting.

Status

Prints the current status of all DSM components to the screen.

-sm mm-sd dd -sy yyyy

(Optional) Specifies alerts that were archived, purged, or both on, and after

a specified month (mm), day (dd), or year (yyyy). The default is all alerts


-sm mm

Includes files created this month (mm) and later.

Limits:01-12

-sd dd

Includes files created on and after this day (dd) of the month.

Limits:01-31

-sy yyyy

Includes files created this year (yyyy) and later.


-o output_file

(Optional) Specifies the CSV file name (output_file). Surround the name with

quotation marks if the name has a space in it.

Default:Today's date in the format yyyymmdd.csv.

Example:20060213.csv for a file created February 13, 2006


54/104



-b|-a|-p

(Optional) Specifies whether to add archived alerts, purged alerts, or both to

the CSV file. Options include the following:

-b

Includes both archived and purged alert records. This is the default.

-a

Includes only archived alert records.

-p

Includes only purged alert records.

The following is a valid example of graphics used in an item element.

Preview

Previews your border selections as you modify them before applying them toyour selection in the document. You can use the following buttons to include

single borders around your text or graphic.

Inserts a border above the selected text or graphic.

Inserts a border below the selected text or graphic.

Inserts a border to the left of the selected text or graphic.

Inserts a border to the right of the selected text or graphic.


55/104


Chapter 7: Message Elements




Message Element Example(see page58)

Definition

A message elementidentifies text communications sent by the program and

displayed to the user. Messages can appear on a console, as a pop-up display, or

in a log file as a result of user action, error, or alert.

Note: A message element does not describe how to troubleshoot an error;

therefore, an error message may require a message element and a

troubleshooting element with reciprocal links.

Message Element Requirements

Message elements always include the following:

The message heading (message number), the message text, or both

The Reason subheading followed by a paragraph that explains what

prompted the message

The Action subheading followed by a paragraph that describes the actions to

take

Message elements may include the following:

Example(see page91)

Graphic(see page45)

Item(see page49)



Procedure(see page61)



56/104



Heading

The message element heading is the message number the user receives from the

program. Do not change the case of any character or rewrite the message

number. If no message number exists, use the message text.

The following are valid examples of message headings:

"CAOP_E_520"

"CAOP_W_PLFINVLD"

"Message record (tokenxxx) has an invalid SPI format...skipping record?"

Message Text

The message element text is the text of the message displayed to the user. Do

not change the case of any character or rewrite the message text.

The following are valid examples of message texts:

"Cannot load DSB file 'name', 'func' rc=rc."

"Message record (tokenxxx) has an invalid SPI format skipping record."

Note:If the message is confusing, contact the developer and offer a clearer

alternative.

Reason

The reason paragraph identifies the problem that caused the message to appear.

Ensure that your reason gives a thorough explanation so the user has a clear

understanding of the message. The reason text is always introduced with the

"Reason:" subheading. The following is a valid example of a message reason:

Reason:

The Event Manager cannot load the Decision Support Binary (policies) file name,

indicated byname, that contains the MSGREC and MSGACT definitions. The most

common reason, indicated by rc,is 2 - file not found.


57/104



Action

The action paragraph describes the action to take to resolve the problem. Ensure

that your action gives a thorough explanation so the user has a clear

understanding of the action to take. In some cases, you can format the action asan item element and reuse it, or you can embed a procedure element as the

action (omit the procedure heading).

Note: If applicable, use the standard topic for contacting Technical Support.

For messages that do not require action, enter None.

The action text is always introduced with the Action: subheading. The following is

a valid example of a message action:

Action:

Give the correct path of the DSB file (copy the msg_db setting), and restartEvent.

The following is a valid example of a message action with an embedded

procedure element.

Action:

Calendars let you specify the days and times when jobs are run and messages

are processed.

To define a calendar

1.

Open Calendar Management.2. Click New on the toolbar.

The Calendar - Detail window opens.

3. Complete the following fields to customize your calendar definition, and click

OK on the toolbar.

The calendar is saved in the database.

More information:

Calendar - Detail Window


58/104

Message Element Example


Message Element Example

CGB0066W

Predicate (predicate_name) is unmapped, the field will be protected to

prevent entry.

Reason:

Attribute views are not mapped between the import and export view. This

condition implies that the predicate (predicate_name) is used only for output and

user input is not allowed.

The generator overrides the protection status of the display field associated with

the attribute and forces the field to be protected.

predicate_name

Identifies the name of the predicate used in the program.

Action:

Verify that the field should be protected. Defining protection for the field

prevents this message.

More information:

Add Field Protection (see page 84)

Field Properties Dialog (see page 125)


59/104

Chapter 8: Principle Elements 59

Chapter 8: Principle Elements



Principle Element Requirements(see page60)

Principle Element Examples(see page60)

Definition

Aprinciple elementprovides concise and relevant hints on what should or should

not be done.

The types of principle elements include the following:

Note

Use notes for supplementary information, usage tips, and so on. Notes

sometimes provide information (such as memory, configuration, or

version-specific information) that applies only in special cases. The note

principle provides information that if removed does not alter or affect the

main topic content.

Follow these guidelines for notes:

Limit the use of notes in a topic. Too many notes can signal that the topic

needs reorganizing.

Use notes to segregate information from a parent topic, which lets youreuse the parent topic more easily.

Use notes for external cross-references such as to other deliverables.

Note:For more information about using a note element for

cross-referencing external deliverables, see the Navigation Standards.

Important

Use important principles to highlight actions or information that might cause

problems to users' systems or data. This principle element provides a

warning that users must read before continuing to read the topic. For

example, the user must heed the important principle to avoid causing major

damage, such as corrupting data or crashing the system.

Follow these guidelines for important principles:

Limit the use of important principles in a topic.

Do not use important principles in tables. The information should be

important enough not to be included in a table where it can be

overlooked.


60/104

Principle Element Requirements


More information:



Message Element Requirements(see page55)Procedure Element Requirements(see page61)


Structure Element Requirements(see page81)


Principle Element Requirements

Principle elements contain the following:

The term used to announce the type of principle element, such as "Note:" or

"Important!" formatted as bold

A short description of what should or should not be done

For an important principle, mention the consequences or resulting impact if

the user does not heed the warning or message in the principle

Principle Element Examples

The following are valid examples of principle elements.

Note: Make sure the format is not only supported but is also applicable. If the

product runs only on Windows NT 4.0 or previous releases, delivering

documentation as a .chm file or JavaHelp is not appropriate.

Important!Do not delete a topic shared by others from the SQL database

without consulting the other members of your project team. When you delete a

topic, Author-it deletes the topic every place it is used.


61/104


Chapter 9: Procedure Elements




Procedure Element Examples(see page66)

Definition

Aprocedure element is a defined set of steps that accomplish a particular task. A

step should have one clear, complete action and one result.

Procedures give instructions about using a product, such as a sequence of inputson a GUI, how to log on to a system, how to install a product, and so on.

More information:



Procedure Element Requirements

Procedure elements always include the following:

Heading

Introduction

Procedure subheading

Steps and results

Procedure elements may include the following:

Example(see page91)

Graphic(see page45)

Item(see page49)





62/104



Heading

The procedure heading provides the first view of the procedure. The heading

should briefly describe what the procedure does. Always begin procedure

headings with an action verb.

The following are valid examples of procedure headings:

"Create a New Document"

"Remove the Library"

Introduction

All procedures must have a short introduction (one or two sentences) explaining

why you would want to perform the procedure. This introduction might be asummary of a more in-depth concept that you have written elsewhere and can

link to from this procedure.

Procedure Subheading

Follow the introduction immediately with a subheading that introduces the steps.

However, do notuse procedure subheadings in one-step procedures.

Format this subheading as follows:

Start with the infinitive "to" and the action verb form of the procedure

heading, perhaps providing more information than the procedure heading. Use sentence-style capitalization (that is, use an initial cap for only the first

letter of the first word) and initial cap proper nouns.

Do not end the subheading with a colon or other punctuation.


63/104



Steps and Results

Procedure steps have the following attributes:

Format of StepsSteps should be numbered.

Number of StepsLimit the number of steps to 7 (+ or -2), whenever

possible. If the number of steps required for the procedure exceeds 9, try

breaking the procedure into several smaller procedures or address the issue

with development.

Content of StepsState only the action that the user should take. Do not

include any result content (usually stated as the purpose of the action). Also,

do not include concept, definition, or entire structure elements. Include only

the item elements that are necessary to the procedure, as in the following

example:

1. Click OK to save the item file.

Rewrite as follows:

1. Click OK.

The file item is saved.

Do not use graphics in procedures unless necessary. Because the user is

typically working in the product, reproducing the UI in a procedure is

unnecessary, unless a graphic demonstrates or clarifies how to use the UI.

Graphics should be minimal and purposeful.

Structure of StepsStart each step with an action verb. If necessary,

conclude with a phrase describing where the action was performed.

Note:If you have a complex dialog with multiple areas on it that can cause

confusion to the reader, begin the step by instructing the user to locate aspecific area. Follow that with the action to perform in that area, for example,

"Locate the Media Configurations section, select the Always Start check box,

and click Apply."

Steps with Multiple ChoicesIf users must choose among multiple tasks,

emphasize the word one in the introductory sentence. Do not use the word or

between steps to indicate a choice, as in the following example:

1. Do oneof the following:

Select Register now (default).

Select Remind me in and enter the duration in the Days field.

Select Do not ask me again.

Click Continue.

If you selected Register now, the registration dialog for the product

appears. If you selected Remind me in days or Do not ask me again, the

installation process ends.


64/104



OS-specific Steps Within a ProcedureIf your product supports more

than one operating system (OS), you may need to document the same

procedure for each OS. In some cases, the procedures vary slightly, so it

makes sense to document the steps in only one procedure topic. But, how do

you indicate the OS differences within one procedure topic?

When documenting OS-specific steps within a single procedure, use a

bulleted list to delineate each OS, and put the name of the appropriate OS in

parentheses at the beginning of the step. The following example shows

formatting and suggested wording:

1. Text for step one.

2. Perform the following task depending on your OS:

(Windows) Text for OS-specific task.

(Ingres) Text for OS-specific task.

3. Text for step three.

This formatting helps keep the step numbering consistent, and it parallels

the way we format procedures that apply to different operating systems (by

including the OS in parentheses in the heading).

Optional StepsTo indicate that a step is optional, place (Optional) at the

beginning of the step, as in the following example:

1. (Optional) Select Use Wildcards.

Wildcard characters are enabled in the From field.

Format of ResultsProvide results for a step on a separate line, as in the

following example:

1. Enter your configuration settings, and click OK.

Your configuration settings are saved to the ABC.dot file.

Content of ResultsResults help users by confirming that they are

following the procedure correctly. When the result is obvious and the

audience is experienced users, results may be omitted. For example, you do

notneed to say Node View appears for the following:

1. Select Node View.

Substeps

Substeps are part of a small, self-contained, related procedure (subprocedure)

that is dependent on the main procedure.

Use substeps sparingly. If you have more than four substeps, break the

subprocedure into a separate procedure and refer the user to that procedure.

Note:When you must create a subprocedure, consider how the process can be

streamlined and provide feedback to development. Subprocedures generally

indicate an unnecessary complication in the

ie standards

Documents