ID Style Guide - Novell€¦ · Introduction 13 Part I Writing and Editing 15 1 Writing Style and Usage 17 1.1 Abbreviations and Acronyms

Information DevelopmentStyle Guide

May 2018

Legal Notice

For information about legal notices, trademarks, disclaimers, warranties, export and other use restrictions, U.S. Government rights, patent policy, and FIPS compliance, see https://www.microfocus.com/about/legal/.

Copyright © 2017 Micro Focus. All rights reserved.

https://www.microfocus.com/about/legal/

Introduction 13

Part I Writing and Editing 15

1 Writing Style and Usage 171.1 Abbreviations and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1.1.1 Abbreviation and Acronym Style and Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181.1.2 Plural Acronyms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.1.3 Possessive Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.1.4 Abbreviating Company Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.1.5 Abbreviating Trademarked Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.1.6 Abbreviating Units of Measure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.1.7 Using Well-Known Industry Acronyms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.1.8 Using Other Industry Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.1.9 Using Articles with Abbreviations and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231.1.10 Using Punctuation with Abbreviations and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

1.2 Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241.3 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.3.1 Email Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241.3.2 Internet Addresses (URLs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.4 Admonitory and Advisory Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251.5 Adverbs of Time and Place . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261.6 Alphabetization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271.7 Ambiguity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271.8 Analogies, Metaphors, and Similes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271.9 Anthropomorphisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281.10 Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281.11 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291.12 Capitalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

1.12.1 Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311.12.2 Acronyms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311.12.3 Callouts and Captions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321.12.4 Computer Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321.12.5 Cross-References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331.12.6 Figure Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331.12.7 Headings and Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331.12.8 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361.12.9 Product Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361.12.10 Proper Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361.12.11 Run-In Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371.12.12 Table Titles and Column Labels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

1.13 Compound Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381.14 Consistent Word Meanings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381.15 Contractions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391.16 Discriminatory Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

1.16.1 Multicultural User Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391.16.2 Cultural Discrimination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391.16.3 Sexist Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401.16.4 People with Disabilities or Illnesses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

1.17 Emphasis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411.18 File Name Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421.19 Gerunds and Participles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421.20 Hyphenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421.21 Modifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431.22 Nouns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

1.23 Numbers and Measurements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441.23.1 Decimals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451.23.2 Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451.23.3 Equations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451.23.4 Fractions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451.23.5 Paper Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461.23.6 Percentages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461.23.7 Punctuating Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461.23.8 Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471.23.9 Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471.23.10 Using Numerals versus Spelled-Out Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

1.24 Personal, Proprietary, and Private Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491.25 Personification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491.26 Plurals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

1.26.1 General Rules for Plurals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501.26.2 Correct Plurals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501.26.3 Plural Feature Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511.26.4 Plural Nouns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511.26.5 Plural and Singular Pronouns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

1.27 Possessives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531.28 Pronouns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531.29 Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541.30 Redundancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551.31 Sentence Structure and Readability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551.32 Spelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571.33 Symbols in Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571.34 Telephone Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571.35 Text Expansion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581.36 “That” versus “Which”. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

1.36.1 Restrictive Clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591.36.2 Nonrestrictive Clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

1.37 Such as, and So Forth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601.38 Time of Day . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601.39 Time Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601.40 Tone, Mood, and Voice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

1.40.1 Tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601.40.2 Mood . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621.40.3 Active Voice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621.40.4 Passive Voice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

1.41 Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631.42 User Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641.43 Verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

1.43.1 Verb Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651.43.2 Verb Tense. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

2 Punctuation 672.1 Ampersand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672.2 Braces or Curly Brackets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672.3 Brackets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672.4 Colons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672.5 Commas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

2.5.1 In a Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682.5.2 With Compound Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682.5.3 With Conjunctive Adverbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692.5.4 With Nonrestrictive Clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

2.5.5 With Subordinating Conjunctions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692.6 Dashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692.7 Ellipsis Marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702.8 Exclamation Points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702.9 Hyphens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702.10 Italics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702.11 Parentheses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712.12 Periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712.13 Quotation Marks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722.14 Semicolons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722.15 Slashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

3 Word Choice and Usage 753.1 American English . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

3.1.1 British English and American English . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753.1.2 Colloquialisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773.1.3 Idioms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773.1.4 Jargon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773.1.5 Slang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

3.2 Terminology Spelling and Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773.3 Latin Terms and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133.4 Abbreviations for Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143.5 Acronyms for Common Technical Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

3.5.1 A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163.5.2 B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163.5.3 C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163.5.4 D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173.5.5 E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173.5.6 F. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183.5.7 G . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183.5.8 H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183.5.9 I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183.5.10 J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193.5.11 K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193.5.12 L. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193.5.13 M . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193.5.14 N . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1203.5.15 O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1203.5.16 P. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1203.5.17 Q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213.5.18 R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213.5.19 S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213.5.20 T. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223.5.21 U . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223.5.22 V . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223.5.23 W . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223.5.24 X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223.5.25 Y. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1233.5.26 Z. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

3.6 GUI Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1233.7 Command Line Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1233.8 Pronouns That Need a Clarifying Noun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1243.9 Transitional Words and Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1253.10 Verbs of Personification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

3.10.1 Cognition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263.10.2 Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

3.10.3 Sight or Perception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1273.10.4 Want or Need. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

3.11 Redundant and Wordy Phrases to Avoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1283.12 Potentially Troublesome Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

3.12.1 A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333.12.2 B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333.12.3 C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343.12.4 D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343.12.5 E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353.12.6 F. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353.12.7 G . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353.12.8 H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353.12.9 I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363.12.10 J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363.12.11 K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363.12.12 L. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363.12.13 M . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363.12.14 N . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373.12.15 O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373.12.16 P. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373.12.17 Q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373.12.18 R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383.12.19 S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383.12.20 T. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383.12.21 U . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393.12.22 V . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393.12.23 W . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393.12.24 X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393.12.25 Y. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393.12.26 Z. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Part II Organization and Formatting 141

4 Product Documentation 1434.1 Structured Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1434.2 Product Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444.3 Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454.4 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464.5 Product Release Types and Version Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1474.6 Versions, Patch Updates, and Service Packs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1484.7 Previous Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494.8 Future Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494.9 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

5 Computer Elements 1515.1 Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1515.2 Graphical User Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

5.2.1 Menus and Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1525.2.2 Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535.2.3 Check Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1545.2.4 Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1545.2.5 Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1555.2.6 Group Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1555.2.7 Ribbons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1565.2.8 Tables or Tabular Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

5.3 Keyboard Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1575.3.1 Arrow Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1575.3.2 Spacebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1575.3.3 Capitalization and Spelling of Common Key Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1585.3.4 Key Combinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

5.4 Network and Computing Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1585.4.1 Domains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595.4.2 Email Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595.4.3 Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595.4.4 HTML or XML Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595.4.5 IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595.4.6 Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605.4.7 Registry Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605.4.8 root. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605.4.9 Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615.4.10 Telephone Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615.4.11 Time Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615.4.12 URLs or Domain Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615.4.13 Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625.4.14 Utilities and Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

5.5 Storage Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625.5.1 Drives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635.5.2 Discs, CDs, and DVDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635.5.3 Disks and Diskettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635.5.4 DOS Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645.5.5 Volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645.5.6 Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645.5.7 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

5.6 Command Line and Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665.7 Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

5.7.1 Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675.7.2 Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1685.7.3 Literal Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1695.7.4 Long Elements (Multi-line) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1695.7.5 Repeated Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705.7.6 Linux and UNIX Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705.7.7 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

5.8 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705.9 Screen Displays and System Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715.10 Software Components in Running Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

5.10.1 Referring to Software Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715.10.2 Presenting Literal I/O in Running Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

5.11 Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

6 Mobile Device Elements 1756.1 Mobile App Design and Usability Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756.2 Mobile Apps Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756.3 Mobile Apps Gesture Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

7 Cross-References 1777.1 Cross-References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1777.2 Relationship Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787.3 Capitalization of Cross-References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787.4 Figures and Tables in Cross-References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787.5 Formatting Cross-References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

7.6 Page Numbers in Cross-References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797.7 Steps in Cross-References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

8 Headings 1818.1 Capitalization of Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828.2 Run-In Headings in Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828.3 Abbreviations in Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

9 Graphics 1859.1 Graphics Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1859.2 Introductions to Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1859.3 Callouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869.4 Captions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869.5 Figure Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869.6 Graphics Production Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

9.6.1 Brand Central. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1879.6.2 Image Gallery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

9.7 Creating Graphics and Screen Captures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

10 Lists 18910.1 General Rules for Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18910.2 Parallelism in Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19010.3 Punctuating Introductions to Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19010.4 Punctuating List Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19110.5 Types of Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

10.5.1 Bullet Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19210.5.2 Checklists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19310.5.3 Ordered Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19410.5.4 Simple Two-Column Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

11 Procedures 19511.1 When to Use Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19511.2 Understanding the Procedure Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19511.3 Procedures Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

11.3.1 Explain the Purpose. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19611.3.2 Keep Procedures Short . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19711.3.3 Make Steps Brief . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19711.3.4 Combine Multiple Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19711.3.5 Distinguish between an Action and a Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19811.3.6 Use Substeps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19911.3.7 Identify Choices or Alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19911.3.8 Simplify Long Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

11.4 Run-in Headings in Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20211.5 Verbs for Use in Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

12 Tables 20312.1 When to Use Table Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20312.2 Guidelines for Using Table Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20412.3 Writing Introductions for Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

13 Legal Notice 20713.1 Legal Notice Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20713.2 Legal Notice Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

13.2.1 Legal Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20813.2.2 Copyright Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20813.2.3 Disclaimer Statement for Release Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20913.2.4 Example Legal Notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

14 Accessibility (Section 508) 21114.1 Accessibility Style. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21114.2 Graphics Style for Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

14.2.1 Description in Running Text to Support Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21214.2.2 Figure Titles to Support Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21214.2.3 Alt Text (HTML) to Support Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21214.2.4 LongDesc Text (HTML) to Support Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

14.3 Table Style for Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21314.4 Publishing Non-Converted HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Part III Structure 215

15 Reuse 217

16 Release Notes 21916.1 Release Notes Style. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

16.1.1 Deliverable Name and Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21916.1.2 Section Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22016.1.3 Cross-Reference Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22016.1.4 Navigation Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22016.1.5 Deliverable Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

16.2 Release Notes Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22116.2.1 Essential Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22116.2.2 Other Possible Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22316.2.3 Topics to Exclude. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

16.3 Resolved Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22516.3.1 Issue and Fix Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22516.3.2 Resolved Issues List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

16.4 Known Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22616.4.1 Defect Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22716.4.2 Issue and Workaround Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

16.5 Updates and SupportLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22716.6 Contacting Micro Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

17 Videos 22917.1 Video Production Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22917.2 Branding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22917.3 Presentation Template and Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23017.4 Video Recording. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23017.5 Voiceover Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23017.6 Video Editing and Post-Production Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23117.7 Video Publication on YouTube . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23117.8 Video Links in Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

18 Glossaries 23518.1 Glossary or Terminology List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23518.2 Term Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23518.3 Definition Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

18.3.1 Defining Nouns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23718.3.2 Defining Verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23718.3.3 Defining Adjectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23818.3.4 Defining Abbreviations and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23818.3.5 Using Abbreviations and Acronyms in Glossary Definitions. . . . . . . . . . . . . . . . . . . . . . . . 23918.3.6 Expanding Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23918.3.7 Definition Errors to Avoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

18.4 Term Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24118.5 Definition Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

18.5.1 Usage Labels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24218.5.2 Cross-References to Related Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24218.5.3 Multiple Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

19 Indexes 24519.1 Index Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24519.2 Index Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24619.3 Index Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24619.4 Index Implementation and Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

20 Help 24920.1 Help Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24920.2 Handling Help in Mobile Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

21 Developer Documentation 25121.1 General Developer Doc Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25121.2 Programming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

21.2.1 Identifying Programming Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25221.2.2 "Function" or "API"? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

21.3 Reference Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25321.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25421.5 Revision Histories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Part IV Appendixes 255

A Preparing Documentation for Editing: A Checklist 257

B Writing and Usage Examples 259B.1 Adverbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259B.2 Introductions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

B.2.1 Introducing Tables and Graphics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260B.2.2 Introducing Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262B.2.3 Introducing SubTocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263B.2.4 Introducing Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

B.3 Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264B.4 That and Which . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

B.4.1 Restrictive Clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

B.4.2 Nonrestrictive Clauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265B.4.3 But What's Essential? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265B.4.4 Using “Who” in Computer Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

B.5 Type or Enter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266B.6 “Their” as a Gender-Neutral Singular Pronoun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267B.7 “Then” as a Conjunction and as an Adverb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

B.7.1 Using “Then” as a Correlative Conjunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268B.7.2 Using “Then” in Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

B.8 Using the Word “Using” in Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270B.9 Verb Tense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271B.10 CPU vs. Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272B.11 RAM vs. Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

C Project Style Sheet Example 273

D Product Terminology 275D.1 Heritage Micro Focus Product Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

D.1.1 A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275D.1.2 B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275D.1.3 C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276D.1.4 D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277D.1.5 E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277D.1.6 F. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277D.1.7 G . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278D.1.8 H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278D.1.9 I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278D.1.10 J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278D.1.11 K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278D.1.12 L. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278D.1.13 M . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279D.1.14 N . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279D.1.15 O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279D.1.16 P . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279D.1.17 Q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280D.1.18 R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280D.1.19 S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280D.1.20 T. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280D.1.21 U . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280D.1.22 V . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281D.1.23 W . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281D.1.24 X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281D.1.25 Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281D.1.26 Z. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

D.2 Heritage Novell Product Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281D.2.1 Open Enterprise Server and NetWare Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281D.2.2 Properties, Attributes, Objects, and Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

E Documentation Updates 291E.1 May 2018 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291E.2 November 2017 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

12

Introduction

The Micro Focus Information Development Style Guide is a collection of rules and guidelines for language style and usage conventions for technical publications and product documentation. Our goal is to convey information clearly, concisely, and consistently, regardless of the delivery format.

A unified style not only enables us to produce information of high linguistic quality, but it also enables us to localize (translate) the information easily and to present it in a variety of print and online formats. Therefore, all Micro Focus Information Developers shall write and edit technical publications and product documentation in accordance with the rules and guidelines in the ID Style Guide. Use it as a resource to answer questions and save time when questions arise.

Part I, “Writing and Editing,” on page 15 Part II, “Organization and Formatting,” on page 141 Part III, “Structure,” on page 215 Part IV, “Appendixes,” on page 255

AudienceThe Writing Style and Usage guidelines define the corporate style, demonstrate good writing practices, and ensure a consistent voice and tone for all external Micro Focus information.The Word Choice and Usage guidelines provide advice on preferred spellings and usage, potential ambiguities, and words and phrases to avoid so that information is clear, concise, and consistent. The advice is not exhaustive. Use the Supplemental Writing Style and Terminology References for additional guidance and examples.

The Organization and Formatting guidelines define style and content development best practices for information developers who prepare product documentation for Micro Focus. The Structural Style guidelines define templates and style guidelines for common deliverables.

Supplemental Writing Style and Terminology ReferencesThe Micro Focus Information Development Style Guide is the authoritative style reference for all technical publications and product documentation. In addition, other resources have been sanctioned as official references to supplement the ID Style Guide where needed.

For writing style and language guidelines that are not addressed by the ID Style Guide, refer to the current edition of these approved third-party style references:

The Chicago Manual of Style, 16th Edition

In addition to the manual, you can consult Chicago Online (http://www.chicagomanualofstyle.org/qanda/topicList.html). The website offers a publicly accessible Q&A with many helpful explanations and answers. You can access the online content of the manual only if you are a subscriber to the website.

Microsoft Manual of Style, 4th Edition Refer to “Part 1: General Topics” in the MMoS.

Introduction 13

http://www.chicagomanualofstyle.org/qanda/topicList.html

For spelling, usage, hyphenation, and other terminology guidelines not addressed in “Word Choice and Usage” on page 75 of the Style Guide, refer to the current edition of these approved third party dictionary references:

Merriam Webster’s Collegiate Dictionary, 11th Edition

You can access Merriam-Webster Dictionary online (https://www.merriam-webster.com/). Microsoft Manual of Style, 4th Edition

Refer to “Part 2: Usage Dictionary” in the MMoS. For other language rules, see “Writing and Usage Examples” on page 259.

These external references are presented throughout this guide as “Chicago,” “Webster’s,” and “MMoS” without reference to version or edition numbers unless particular topic numbers are cited.

Technology ResourcesThe following technology resources are helpful for background information:

The Acronym Finder (http://www.acronymfinder.com/) is an exhaustive list of acronyms and expansions from many different industries and resources.

The ComputerUser High-Tech Dictionary (http://www.computeruser.com/resources/dictionary/) is one of several dictionaries specific to the software and hardware industry.

The Webopedia (http://webopedia.com/) online technical dictionary is a useful source for computing and information technology terminology and definitions.

The Whatis.com (http://whatis.techtarget.com/) online reference is a useful source for understanding technical terms and concepts.

The Computer Dictionary Online (http://www.computer-dictionary-online.org/) has definitions for standard computer terminology, as well as a collection of “geek-speak” for background information.

If you want to do a quick online lookup of a word, Dictionary.com (http://dictionary.reference.com/) searches a number of standard dictionaries and presents the results as a list. However, this site is “authoritative” only if the results are also in one of our authorized sources.

The Microsoft Windows User Experience Guidelines (https://msdn.microsoft.com/en-us/library/windows/desktop/dn688964(v=vs.85).aspx) gives official guidelines for user interface developers and contains detailed information about designing a user interface for Windows, including style guidelines for interface text.

FeedbackTo report problems with individual pages, you can use the comment on this topic link at the bottom of each page of the online documentation.

You can request a change or addition to the ID Style Guide by opening a Bugzilla Request (https://bugzilla.novell.com). Select New > Doc Tools > Doc Editing, then select Style Guide in the Component list.

Documentation UpdatesFor the most recent version of the Micro Focus Information Development Style Guide, visit the Information Development Resources web page (http://www.novell.com/documentation/beta/docguides/).

14 Introduction

https://www.merriam-webster.com/

https://msdn.microsoft.com/en-us/library/windows/desktop/dn688964(v=vs.85).aspx

https://bugzilla.novell.com

http://www.novell.com/documentation/beta/docguides/

http://www.acronymfinder.com/

http://www.computeruser.com/resources/dictionary/

http://webopedia.com/

http://whatis.techtarget.com/

http://www.computer-dictionary-online.org/

http://dictionary.reference.com/

https://www.merriam-webster.com/

I IWriting and Editing

Writing and Editing sets standards for corporate style, grammar, terminology, and punctuation for content in external-facing documentation. These guidelines clarify preferred style when many alternatives exist. They ensure that multiple writers present a seamless experience for our users across diverse products and deliverables.

Chapter 1, “Writing Style and Usage,” on page 17 Chapter 2, “Punctuation,” on page 67 Chapter 3, “Word Choice and Usage,” on page 75

Writing and Editing 15

16 Writing and Editing

1 1Writing Style and Usage

Follow these language style, punctuation, and usage rules as you write and edit documentation.

Section 1.1, “Abbreviations and Acronyms,” on page 18 Section 1.2, “Accessibility,” on page 24 Section 1.3, “Addresses,” on page 24 Section 1.4, “Admonitory and Advisory Paragraphs,” on page 25 Section 1.5, “Adverbs of Time and Place,” on page 26 Section 1.6, “Alphabetization,” on page 27 Section 1.7, “Ambiguity,” on page 27 Section 1.8, “Analogies, Metaphors, and Similes,” on page 27 Section 1.9, “Anthropomorphisms,” on page 28 Section 1.10, “Articles,” on page 28 Section 1.11, “Audience,” on page 29 Section 1.12, “Capitalization,” on page 31 Section 1.13, “Compound Words,” on page 38 Section 1.14, “Consistent Word Meanings,” on page 38 Section 1.15, “Contractions,” on page 39 Section 1.16, “Discriminatory Language,” on page 39 Section 1.17, “Emphasis,” on page 41 Section 1.18, “File Name Extensions,” on page 42 Section 1.19, “Gerunds and Participles,” on page 42 Section 1.20, “Hyphenation,” on page 42 Section 1.21, “Modifiers,” on page 43 Section 1.22, “Nouns,” on page 44 Section 1.23, “Numbers and Measurements,” on page 44 Section 1.24, “Personal, Proprietary, and Private Information,” on page 49 Section 1.25, “Personification,” on page 49 Section 1.26, “Plurals,” on page 49 Section 1.27, “Possessives,” on page 53 Section 1.28, “Pronouns,” on page 53 Section 1.29, “Recommendations,” on page 54 Section 1.30, “Redundancy,” on page 55 Section 1.31, “Sentence Structure and Readability,” on page 55 Section 1.32, “Spelling,” on page 57 Section 1.33, “Symbols in Text,” on page 57 Section 1.34, “Telephone Numbers,” on page 57

Writing Style and Usage 17

Section 1.35, “Text Expansion,” on page 58 Section 1.36, ““That” versus “Which”,” on page 59 Section 1.37, “Such as, and So Forth,” on page 60 Section 1.38, “Time of Day,” on page 60 Section 1.39, “Time Zones,” on page 60 Section 1.40, “Tone, Mood, and Voice,” on page 60 Section 1.41, “Trademarks,” on page 63 Section 1.42, “User Names,” on page 64 Section 1.43, “Verbs,” on page 65

1.1 Abbreviations and AcronymsAn abbreviation is a shortened form of a word or phrase. An acronym is an abbreviation formed from the letters (usually the first) from several words. Some acronyms are pronounced as words, while others (sometimes referred to as initialisms) are pronounced by pronouncing each letter.

Do not use Latin terms or abbreviations. For alternative terms, see Section 3.3, “Latin Terms and Abbreviations,” on page 113.

For specific abbreviations, see Section 3.2, “Terminology Spelling and Usage,” on page 77. For units of measure, see Section 1.1.6, “Abbreviating Units of Measure,” on page 21.

For rules governing the use of abbreviations and acronyms, see Chicago. These guidelines supplement the information found there.

Section 1.1.1, “Abbreviation and Acronym Style and Usage,” on page 18 Section 1.1.2, “Plural Acronyms,” on page 20 Section 1.1.3, “Possessive Acronyms,” on page 20 Section 1.1.4, “Abbreviating Company Names,” on page 20 Section 1.1.5, “Abbreviating Trademarked Terms,” on page 21 Section 1.1.6, “Abbreviating Units of Measure,” on page 21 Section 1.1.7, “Using Well-Known Industry Acronyms,” on page 22 Section 1.1.8, “Using Other Industry Acronyms,” on page 22 Section 1.1.9, “Using Articles with Abbreviations and Acronyms,” on page 23 Section 1.1.10, “Using Punctuation with Abbreviations and Acronyms,” on page 23

1.1.1 Abbreviation and Acronym Style and Usage Use acronyms sparingly and only when you are certain they can be understood by everyone.

Some languages completely disallow the use of abbreviations. In most cases, they must be spelled out when translated, making text expansion and graphics sizing a problem.

English: PrintQ

French: File d’attente d’impression

18 Writing Style and Usage

You can use standard abbreviations for well-known countries without spelling them out on first use.

Abbreviations and acronyms that are common to users of a specific product or technology do not need to be spelled out, but they should be noted in a project style sheet to ensure consistent use.

When you spell out an abbreviation or acronym, present the spelled-out version as you would present it in running text.

Do not use capitalization or a special font to distinguish the letters used to create the abbreviation or acronym.

For acronyms that are not familiar to your audience, use the extended form at the first occurrence in a topic followed by the acronym in parentheses. After that, use the acronym for all subsequent references.

Usage for a given acronym should be consistent throughout a book or doc set. For acronyms that are familiar to your audience, you can use the acronym first, followed by the

extended form in parentheses. After that, use the acronym for all subsequent references.

Usage for a given acronym should be consistent throughout a book or doc set. Do not spell out a phrase and give its abbreviation or acronym in parentheses in a heading.

Spell product-specific phrases or component names in the heading. Show the abbreviation or acronym parenthetically at the first reference in text.

Examples: U.K.U.S.

Wrong: LAN (Local Area Network)

Right: LAN (local area network)

Wrong: modem (MOdulator / DEModulator)

Right: modem (modulator / demodulator)

Example: Your system should have an uninterruptible power supply (UPS). The UPS protects your data from corruption in case of a power failure.

Example: The CAD (computer-aided design) application requires a high-performance desktop.

Wrong (heading): Access Connector Toolkit (ACT)

Right (heading and following text): Access Connector Toolkit

You can use the Access Connector Toolkit (ACT) to create custom connectors to web services and applications.


Show common industry abbreviations or acronyms in the heading. Show the abbreviation or acronym in the text. Spell out the phrase parenthetically at the first reference in text.

Do not use the spelled-out version and the abbreviation or acronym interchangeably within a topic. Either use one or the other, or spell it out on its first occurrence, then use the abbreviation on subsequent occurrences within a section.

If you use an unfamiliar abbreviation to save space within a table or illustration, ensure that you explain or expand it in the introduction or immediately following the table or illustration.

Do not form verbs from acronyms.

1.1.2 Plural AcronymsForm plural acronyms by adding a lowercase “s”, unless it is a unit of measure. See Section 1.1.6, “Abbreviating Units of Measure,” on page 21.

1.1.3 Possessive AcronymsAvoid acronyms in the possessive case. Instead, rewrite the sentence.

1.1.4 Abbreviating Company NamesDo not use the initials MF in documentation as an abbreviation for Micro Focus. The initials have an unfortunate connotation in the U.S.

Follow these guidelines when you use third-party company names in documentation.

Wrong (heading): Customizing the Graphical User Interface (GUI) for Client Workstations

Right (heading and following text): Customizing the GUI for Client Workstations

To customize a client workstation’s GUI (graphical user interface) to reflect a user’s preferences,… After customization, the GUI menus, buttons, and pop-ups are…

Wrong: After you have COMPSURFed the hard disk, you can install the disk in the file server.

Right: After you run COMPSURF on the hard disk, you can install the disk in the file server.

Wrong: NIC’s

Right: NICs

Wrong: 20 MBs

Right: 20 MB

Wrong: The PROM’s location varies from board to board.

Right: The location of the PROM varies from board to board.


1.1.5 Abbreviating Trademarked TermsDo not use an abbreviation or acronym for a trademarked term unless it is also a trademarked term.

For information about trademarked abbreviations or acronyms, see the company trademark information.

1.1.6 Abbreviating Units of MeasureFollow these guidelines for using abbreviations of units of measure.

Abbreviate a unit of measure when it is preceded by a numeral.

Insert a space between a number and a multiple-letter abbreviation, even when it is used as a compound adjective.

Do not insert a space between a number and a single-letter abbreviation.

Do not add the letter “s” to form the plural of an abbreviation of a unit of measure.

In video or audio media, pronounce the abbreviated unit of measure as you would if the term were spelled out. For example, pronounce MB as “megabyte” or “megabytes”, depending on the number it modifies, not “em-bee”.

For a list of abbreviations for technology units of measure, see “Abbreviations for Units of Measure” on page 114.

Company

Microsoft Do not abbreviate.

HP Proper name. Abbreviation of “Hewlett-Packard”.

IBM Proper name. Do not spell out.

Example: You cannot use NMA software for NetWare Management Agent software because NMA is not a trademarked term.

Example: You can use NLM software for NetWare Loadable Module software because both terms are trademarked.

Wrong: 200 bits per second

Right: 200 bps

Example: The system requires a 10 GB hard drive.

Example: The computer uses a 9V backup battery.

Wrong: 20 MBs

Right: 20 MB


For information about presenting dimensions, see “Dimensions” on page 45.

1.1.7 Using Well-Known Industry Acronyms Some industry acronyms are so well-adopted that have evolved to be used as words. Use them

without expanding them on first use.

Some acronyms are well-known industry terms. Use them and variants without expanding them on first mention.

Do not spell out acronyms on first mention for well-known file name extensions, such as CSV, DOC, JPEG, MP3, MP4, PDF, PNG, TXT, XLS, and so on.

1.1.8 Using Other Industry AcronymsFor less-well-known industry acronyms, spell out the phrase and parenthetically identify the acronym the first time the phrase appears in a topic. Use the acronym in all subsequent references.

See Section 3.5, “Acronyms for Common Technical Phrases,” on page 115 for a list of common technical phrases and their acronyms.

Examples: Basicmodemtelnet

ANSI DOS I/O RAID URL

ASCII DVD MAC address RAM USB

BIOS DVD-R, DVD-RW MIME ROM VHF

CAPTCHA DVD-ROM MS-DOS SCSI WORM

CD ESQL MySQL SGML WYSIWYG

CD-R, CD-RW GNU NetBIOS SQL XHTML

CD-ROM GUI NIC SSH XML

CLOB HTML OLE TCP/IP XSL

CPU HTTP PC UHF XSS

DBA HTTPS PostgreSQL UI

Example: Specify the appropriate globally unique identifier (GUID).


1.1.9 Using Articles with Abbreviations and AcronymsAbbreviations and acronyms that are either combined with generic nouns or that can be pluralized require a definite or indefinite article. Use “a” or “an” based on the pronunciation of the first letter.

For example, the following table demonstrates articles applied to acronyms based on their pronunciation. With some terms, the article that precede a term will depend on how your target audience pronounces it. For SQL, Microsoft and Oracle prefer “sequel” for their database products, while programmers using the database language prefer “ess-cue-ell”. You might write “a SQL server” and “an SQL query”, and both usages would be correct.

No article is required when an abbreviation or acronym standing alone cannot be made plural, even if the term that it stands for requires an article. For example, an acronym for an organization or program cannot be made plural, but the spelled-out name requires an article.

1.1.10 Using Punctuation with Abbreviations and Acronyms If an abbreviation or acronym contains an internal period, do not put a space after the period.

If an abbreviation or acronym with a terminal period falls at the end of a sentence, omit the second period at the end of the sentence.

Abbreviation or Acronym

Pronunciation Sound Article Usage

ASCII ass-kee vowel an ASCII character

ATM ay-tee-em vowel an ATM connection

B2B bee-to-bee consonant a B2B website

DoS dee-oh-ess consonant a DoS attack

LAN lan (like can) consonant a LAN connection

MLID em-ell-eye-dee vowel an MLID file

MySQL my-ess-cue-ell consonant a MySQL server

SCSI scuzzy consonant a SCSI bus

SQL see-quel consonant a SQL server

SQL ess-cue-ell vowel an SQL server

Example: We recently announced the Technical Support Alliance (TSA) organization. TSA ensures that...

Example: We recently joined the Defense Advanced Research Projects Agency (DARPA) organization. DARPA is sponsoring a symposium on technology and research opportunities.

Examples: a.m.p.m.

Example: Back up the server each morning before 6:00 a.m.


1.2 AccessibilityAccessibility refers to the design and delivery of information that all potential users are able to access in an equal and positive way.

For information about best practices for developing accessible information, see Chapter 14, “Accessibility (Section 508),” on page 211.

For information about avoiding discriminatory language in writing, see “Discriminatory Language” on page 39.

1.3 Addresses If possible, avoid references to information that changes often, such as telephone numbers,

technical support organizations, or Internet addresses (URLs). If you must use volatile information, place it in a separate paragraph so that it can be easily

removed or changed when the documentation is localized. Do not expose real street addresses, phone numbers, email addresses, DNS names or IP

addresses, URLs and so forth in examples, videos, or screen captures.

1.3.1 Email Addresses Use lowercase letters when indicating an email address.

Do not hyphenate email addresses. Do not use a font change on an email address in running text or in text on a separate line.

1.3.2 Internet Addresses (URLs) Use lowercase letters when indicating an Internet address (URL).

If a case-sensitive URL might cause difficulty for your audience, use the necessary capitalization in your document and make a point of telling the reader that this is exactly how it must be typed.

When writing out a URL, always use forward slashes unless the URL must use backslashes. Do not hyphenate Internet addresses to make a break at the end of a line. Use a monospace font for an example URL in running text or in text on a separate line. Do not

create a live link for the URL.

Examples: [email protected][email protected]

Examples: http://www.microfocus.com/https://home.example.com/

Example: Use your web browser to go to the URL your administrator gives you, such as http://server/gw/webacc.


Do not use a font change on a URL that is formatted as a live link. Live links use colored text, which is sufficient to identify them from surrounding text. A different colored text distinguishes links that have been followed.

1.4 Admonitory and Advisory ParagraphsUse admonitory and advisory paragraphs conservatively to highlight specific types of information. They are formatted in a distinctive manner to draw the reader’s attention to them.

Warning or Caution Warns of potential loss of data, equipment damage (to hardware), or physical hazards to the user. Use the term appropriate for your authoring tool: “Warning” or “Caution”.

Important Introduces vital information (for example, about a system or software requirements) that deserves particular attention.

Tip Introduces guidelines or tips (for example, about fine-tuning or optimizing) that might be applicable to the reader’s site or situation. They contain helpful but noncritical information: additional details alternative methods hints shortcuts related information

Example: For information about publicly available NTP (network time protocol) servers, see NTP Pool Time Servers (http://support.ntp.org/bin/view/Servers/NTPPoolServers).

Example: For Micro Focus legal information, see https://www.microfocus.com/about/legal/.

Example: WARNING: Using an older version of the software to update a database created in a newer version can cause the data to become corrupted.

Example: IMPORTANT: Name your post office carefully. After it is created, the name cannot be changed.

Example: TIP: If you are installing the client software on several workstations that have network connections, using one of the network installation options is generally better.


http://support.ntp.org/bin/view/Servers/NTPPoolServers

http://support.ntp.org/bin/view/Servers/NTPPoolServers


Note Use a Note to present information the user needs to know to accomplish a task or to understand a feature.

Limit the use of admonitory and advisory paragraphs: Avoid successive admonitory or advisory paragraphs. Avoid using more than one admonitory or advisory paragraph per page. Avoid using Notes or Tips in procedures.

In a procedure, any text in addition to the step is used to briefly explain the step or its result, or to give additional information, which is also what a Note or a Tip is intended to do. Rather than format explanatory paragraphs in procedures as Notes, use a simple Para tag instead. If the information is essential, not just an explanation, it is appropriate to use an Important note or a Warning (Caution) note in a procedure.

1.5 Adverbs of Time and Place Use adverbs that indicate time and place only to indicate time and place. Avoid using these

adverbs to show contrast or comparison.

Adverbs such as “where,” “while,” and “when” are frequently and incorrectly used to mean “in contrast to” or “in comparison with.”

Information Type Example

To provide information that needs to be emphasized regarding past versions or information taken from previous versions.

NOTE: WordPerfect Office, the predecessor of GroupWise, was originally designed by WordPerfect Corporation, Hence, the WP in wpdomain.db. Some naming conventions have been preserved for backward compatibility.

To provide special emphasis for something that would waste time or be frustrating to the user, even though it might not be critical or fatal.

NOTE: NPRINT and NPRINTER are not the same. NPRINT is a command line utility, and NPRINTER is an NLM program.

To provide necessary information that does not fit into the context of the paragraph.

This example note refers to a graphic with multiple steps, some of which are conditional.

NOTE: Steps shown in reverse color are conditional.

To emphasize information regarding version compatibility or platform-specific information.

NOTE: For Windows, if the POA does not respond to Exit, you can close the POA operations screen to stop the POA.

NOTE: For UNIX, if the POA does not respond to Exit, you can close the POA operations screen or use the UNIX kill command to stop the POA.

Wrong: You can install the application on one server, while your eDirectory tree is on another.

Right: You can install the application on one server and your eDirectory tree on another.


For usage guidelines and examples for the following specific words, see Section 3.2, “Terminology Spelling and Usage,” on page 77.

“as, since, for” on page 80 “once” on page 103 “where” on page 112 “while” on page 112

1.6 Alphabetization When you organize information, use a chronological, sequential, or logical order wherever

possible. If there is no clear order, use alphabetization if you feel it helps readers find what they need. However, lists are not re-sorted in alphabetical order when they are translated.

Use word-by-word alphabetization, according to the rules given in Chicago. Sort functions in programming tools might use letter-by-letter sorting for strings.

1.7 Ambiguity In general, refer to a software component (command, function, utility, system call, or library

routine) by name only.

Whenever possible, avoid using terms that possess more than one potential interpretation. Provide context for understanding, or use a more specific term.For example, the term BdpParameterCollection can refer to an object, a class, or other entity type.

For example, the term mkdir can refer to a command or a system call.

Use a term in the same manner to ensure consistency throughout an entire documentation set. Reduce ambiguity by avoiding synonyms and using one term per concept.For example, if you refer to an object as a data provider in one section of a document, do not refer to the same object as a database provider in another section. A reader might conclude that a difference exists between the two references.

Do not overuse pronouns, particularly “it” and “this”. See Section 1.28, “Pronouns,” on page 53.

1.8 Analogies, Metaphors, and Similes Use figurative language with discretion.

Example: Configure the server by running iManager.

Wrong: BdpCommand returns an empty BdpParameterCollection.

Right: BdpCommand returns an empty BdpParameterCollection object.

Wrong: mkdir calls mkdir.

Right: The mkdir command invokes the mkdir system call.


Technical writing requires clear, concrete prose. Using analogies, metaphors, and similes always risks confusing the audience, especially the international audience. In addition, most figurative language is very hard to translate. If it is translated literally, it could mean something different from what the writer intended.

If you use figurative language, ensure that it is not culture-specific. The tree metaphor chosen to describe and develop a directory service architecture is generally easy to understand the world over. The following are some examples of fairly safe uses of simile, metaphor, and analogy:

1.9 AnthropomorphismsAvoid anthropomorphisms. Do not attribute human characteristics to inanimate objects. See Section 1.25, “Personification,” on page 49 and Section 3.10, “Verbs of Personification,” on page 126.

1.10 Articles Use an indefinite article like “a” or “an” when you refer to one of the following elements:

A member of a group or class.For more information, contact an administrator.

Wrong: NSS can mount any size NSS volume with as little as 1 MB of memory and with a small footprint size of 2 MB.

Right: NSS can mount any size NSS volume with as little as 1 MB of memory for the volume and 2 MB for processing purposes.

Example: A personal signature applied to a paper document indicates the authenticity of the document, as a digital signature indicates the authenticity of electronic data.

Example: The file system is analogous to an office filing system, as illustrated in the following figure.


A type or example of something.In a table, a row intersects with a column to create a cell.

Anything for the first time.In some cases, a core process consists of multiple tasks.

Use the definite article “the” when you refer to one of the following elements: Something that you have already referenced.

Someone or something that you must specifically identify.

Do not use the word “the” before the name of a product.

However, you can use the word the before the names of tools and utilities that are an integral part of a product, such as the Code Editor, the Tool Palette, or the Designer Surface.

Use indefinite articles “a” or “an” with abbreviations or acronyms based on the initial vowel (“an”) or consonant (“a”) sound when you pronounce them. See Section 1.1.9, “Using Articles with Abbreviations and Acronyms,” on page 23.

1.11 Audience Identify your intended reader.

When you know who your reader is, the job of tailoring the language, vocabulary, and content of your documentation is much easier. You know how much technical experience your reader has and how much explanation is needed in your writing.

For example, you can count on an administrator being familiar with the basic operating system terminology and actions. However, you might need to include or explain advanced functions or commands.

Keep the reader in mind when writing documentation: Address the reader’s needs and not the program’s. Be task-oriented. Explain how the reader can do things instead of how the program

operates or is organized. If information about how a program operates or is organized is valuable, put it in a

secondary location and refer to it.For more information about presenting instructions, see Chapter 11, “Procedures,” on page 195.

Address your reader truthfully and positively. Do not make claims your product cannot live up to, but do not stress negative points. Focus instead on the positive.

Example: In some cases, a core process consists of one or two tasks. In other cases, the core process consists of several linked procedures that the user must follow sequentially to attain a desired result.

Example: Type your password in the Password text box.

Wrong: Install the Developer Studio.

Right: Install Developer Studio.


Avoid absolutes when describing our products. Be careful using the following phrases:

AlwaysCompletely compatibleOne hundred percent compatible

Use the pronouns “we” and “you” instead of nouns when addressing the reader.

Use the phrase “you can” only when the documentation presents a genuine option.

Consider using common rather than technical terminology.Although technical terminology is necessary in many cases (such as when you are discussing specific software products), in other cases common language can serve better. Some of the terms that are common in the computer industry are easily replaced with terms that have wider acceptance. Our growing customer base includes novice computer users as well as network administrators. Using common terms helps novice users and also helps the translators who localize our documentation.

Use industry terms instead of (or in addition to) terms specific to an individual company.

For additional rules about addressing your audience, see “Tone, Mood, and Voice” on page 60. Some usage guidelines are also included in Section 3.2, “Terminology Spelling and Usage,” on page 77.

Negative: You cannot use most word processors to edit a text file.

Positive: With OpenOffice you can retrieve, edit, and save text files.

Wrong: The user can create a new password…

Right: You can create a new password…

Wrong: You can omit words that do not add value to a sentence.

Right: Omit words that do not add value to a sentence.

Company Usage Industry Usage

Use SBCON to back up the NSS volume. To back up the NSS volume, use a data backup and restore solution such as the SBCON utility or a third-party enterprise backup application.

The directory schema is expanded during the install. You need the Supervisor right to expand the schema for the tree.

The directory schema is expanded during the install. You need the schema administrator user name and password to expand the schema for the tree.


1.12 CapitalizationOur documentation follows the basic capitalization rules found in Chicago. This section lists exceptions and variations, and reiterates some of the Chicago rules.

Some capitalization guidelines are also included in Chapter 3, “Word Choice and Usage,” on page 75.

Section 1.12.1, “Abbreviations,” on page 31 Section 1.12.2, “Acronyms,” on page 31 Section 1.12.3, “Callouts and Captions,” on page 32 Section 1.12.4, “Computer Elements,” on page 32 Section 1.12.5, “Cross-References,” on page 33 Section 1.12.6, “Figure Titles,” on page 33 Section 1.12.7, “Headings and Titles,” on page 33 Section 1.12.8, “Lists,” on page 36 Section 1.12.9, “Product Names,” on page 36 Section 1.12.10, “Proper Names,” on page 36 Section 1.12.11, “Run-In Headings,” on page 37 Section 1.12.12, “Table Titles and Column Labels,” on page 37

1.12.1 Abbreviations Use lowercase letters for abbreviated words unless the term abbreviated is a proper noun or a

term with special capitalization.

For abbreviations that are proper nouns, capitalize them exactly, even if the words the abbreviation represents are not capitalized.

For abbreviations used for units of measure, follow the capitalization guidelines in “Abbreviating Units of Measure” on page 21.

For capitalization of specific abbreviations, follow the capitalization guidelines in Section 3.2, “Terminology Spelling and Usage,” on page 77.

1.12.2 Acronyms Capitalize each letter of the phrase that forms the acronym, unless the abbreviated phrase forms

a proper noun or industry term with special capitalization.

Example: bits per second (bps)

Example: Hertz (Hz)

Example: kilobits per second (Kbps)

Example: megabit (Mb)

Example: megabyte (MB)


Some acronyms have become words, in which case, you capitalize and use it as a word or proper noun.

Capitalize the acronym exactly, even if the words the acronym represents are not capitalized.

When spelling out an acronym, use the capitalization given in Section 3.2, “Terminology Spelling and Usage,” on page 77, in “Abbreviating Units of Measure” on page 21, or in Webster’s.

1.12.3 Callouts and CaptionsCapitalize the first letter of the first word of callouts and captions for graphics and any other letters as necessary, such as product names.

For more information about the treatment of callouts and captions, see “Callouts” on page 186 and “Captions” on page 186.

For information about using figure descriptions, see “Graphics Style for Accessibility” on page 212.

For information about using figure titles, see “Figure Titles” on page 33 and “Figure Titles to Support Accessibility” on page 212.

1.12.4 Computer ElementsFor information about the capitalization of computer elements such as file names, path names, and email addresses, see Chapter 5, “Computer Elements,” on page 151, especially the following sections:

Case Sensitivity Commands Email Addresses IP Addresses Domains Servers

Example: Amazon Web Services (AWS)

Example: Asynchronous Transfer Mode (ATM)

Example: distributed denial of service attack (DDoS)

Example: SUSE Linux Enterprise Server (SLES)

Example: Worldwide Interoperability for Microwave Access (WiMAX)

Example: Bash

Example: modem

Example: host bus adapter (HBA)

Example: software as a service (SaaS)

Example: uninterruptible power supply (UPS)


Hosts Drives Volumes Directories Files

1.12.5 Cross-References If your authoring tool has an automatic cross-reference feature, use it to create properly

capitalized cross-references. If you must create cross-references manually, capitalize cross-references to specific chapters,

sections, parts, steps, and so forth.

If you cross-reference to a different book, give the heading that’s closest to the destination text and give the book name, but not the full path (that is, no intermediate headings).

Do not capitalize general references.

1.12.6 Figure TitlesCapitalize figure titles according to the rules in Section 1.12.7, “Headings and Titles,” on page 33.

For more information about using figure titles, see Section 9.5, “Figure Titles,” on page 186 and “Figure Titles to Support Accessibility” on page 212.

For information about using figure descriptions, see “Alt Text (HTML) to Support Accessibility” on page 212 and “LongDesc Text (HTML) to Support Accessibility” on page 213.

For more information about the treatment of callouts and captions, see “Callouts” on page 186 and “Captions” on page 186.

1.12.7 Headings and TitlesChicago prefers headline-style capitalization, but it allows for the use of down-style capitalization.

Headline style: Capitalization is governed mainly by emphasis and grammar. See Chicago (16th ed.) 8.157–159, and 8.166.

Example: Refer to “Installing a File Server” for instructions.

Example: Repeat Step 3 through Step 5.

Wrong: For information about software prerequisites, see “Table 1” in “System Requirements” in the PlateSpin Migrate Installation Guide.

Right: For information, see “Table 1: Software Prerequisites” in the PlateSpin Migrate Installation Guide.

Wrong: Refer to the vendor Installation Instructions.

Right: Refer to the vendor installation instructions.


Down style: Capitalization is governed by sentence case rules: capitalize the first word and all proper nouns and some derivatives of them. See Chicago (16th ed.) 8.1 and 8.46.

NOTE: For existing projects, follow the heading style for your doc set. For new doc projects, we recommend headline-style capitalization.

For headings and titles, follow these headline-style guidelines that reiterate the rules from Chicago, along with exceptions and variations.

Capitalize the first word, the last word, and the first word after a colon. Capitalize the first letter of each major word, regardless of length. Major words include nouns,

pronouns, verbs, adjectives, adverbs, and subordinating conjunctions.

Capitalize even the short and sometimes easy-to-overlook major words such as “are”, “be”, “if”, “is”, “it”, and “its”.

Do not capitalize articles, coordinating conjunctions, and prepositions, regardless of length, unless it is the first or last word, or unless it follows a colon. Capitalize prepositions that are used adjectivally or adverbially.

Common Subordinating Conjunctions:

as because if though wherever

although before now unless whether

after even once until which

as if even if since when while

as soon as even though than whenever who

as though how that where why

Example: About This Manual

Example: Printing the Presentation Space without the OIA

Example: Installing a Self-Signed Certificate on an Android Device

Example: A Re-Enabled User Has a Role That Was Previously Assigned

Example: What Is Slowing Down Your Network and How to Fix It

Articles:

a

an

the


Capitalize the article, coordinating conjunction, or preposition if it is the first or last word in the heading or title.

Capitalize the article, coordinating conjunction, or preposition if it follows a colon.

Lowercase the word “to” as part of an infinitive unless it is the first word in the heading or title, or if it follows a colon.

Capitalize both words in a compound verb that includes a preposition.

Capitalize both words in a hyphenated compound.

Capitalize only the first word in a hyphenated prefix-suffix combination, unless it is the first or last element in the heading or title.

Coordinating Conjunctions:

and for or yet

but nor so

Common Prepositions:

about around by in out under

above as during of over up

across at for off through with

among between from on to within

Example: Configuring the Server You Want to Log In To

Example: To Back Up Files with SBACKUP

Example: About This Manual

Example: The Enterprise Mission: To Boldly Go Where No One Has Gone Before

Example: How to Back Up Files with SBACKUP

Example: To Back Up Files with SBACKUP

Example: The Enterprise Mission: To Boldly Go Where No One Has Gone Before

Example: Setting Up the Workstation

Example: Logging In to the Network from a Client Workstation

Example: Using Drop-Down Lists

Example: Supported Host-Dependent Features

Example: Installing a Self-Signed Certificate on an Android Device


File and directory names that are lowercase in running text should use initial capitals in headings, unless they are lowercase because of case-sensitivity.

Use lowercase for proper nouns that would be lowercase in running text, and preserve the mix of capital and small letters, unless the heading or title is in all capitals.

Use lowercase for abbreviations or acronyms that would be lowercase in running text because of case-sensitivity.

1.12.8 ListsCapitalize the first letter of the first word in each list item and any other words as necessary, such as product names.

For more information about lists, see “Lists” on page 189.

1.12.9 Product Names Use established conventions to capitalize product names, trademarks, and trade names.

Present generic product technologies in lowercase.

1.12.10 Proper Names Capitalize common nouns when they are used as an integral part of the proper name for a

person, place, or thing.

Example: Using a Backup to Re-create the Directory

Example: Re-Creating the Directory

Example: Performing a Re-Creation

iPrint iPhone iOS

iManager iPod reCAPTCHA

Examples: bps (bits per second)cps (cycles per second)ms (millisecond)

CloudAccess GroupWise PostScript

COBOL NetWare SUSE

eDirectory PlateSpin ZENworks

Example: uninterruptible power supply

Example: network operating system

Example: development tools


Do not capitalize common nouns when they are used alone in subsequent references.

1.12.11 Run-In HeadingsIf your authoring tool allows you to create a run-in heading at the beginning of a paragraph, use the following rules for punctuation between the heading and the paragraph:

Do not use multiple spaces or a single space with no punctuation following the Title.

You can use either colons or periods following the Title, but be consistent within a book.

Avoid using a hyphen, em dash, or en dash following the Title.

Use a single space after a colon or period. Some authoring tools automatically insert the space. Use either sentence-style capitalization or heading-style capitalization in the run-in heading,

depending on the context. Use sentence-style capitalization in the body of the paragraph.

1.12.12 Table Titles and Column Labels Capitalize table titles and row and column labels according to the rules for headings and titles.

See “Headings and Titles” on page 33.

Example: System Administrator user

Example: Click Properties.

Example: Open the Driver Health Configuration page…

Example: Log in as administrator.

Example: Specify values for each of the properties.

Example: To view the driver health status…

Wrong: Replace deletes existing text objects.

Wrong: Replace A text tool that deletes existing text objects.

Right: Update: Updates all existing objects with new information.

Right: Update. Updates all existing objects with new information.

Wrong: Update - Updates all existing objects with new information.

Wrong: Update — Updates all existing objects with new information.

Wrong: Update – Updates all existing objects with new information.


1.13 Compound Words See Chicago for rules on creating and using compound words. Some usage guidelines are also included in Chapter 3, “Word Choice and Usage,” on page 75.

1.14 Consistent Word MeaningsUse the following guidelines when selecting the vocabulary for your documentation. Some specific usage guidelines are also included in Chapter 3, “Word Choice and Usage,” on page 75.

Use terminology consistently.

When you select a term to signify a specific concept, use that term every time you refer to that concept. Do not use variations (synonyms) of the term.

For example, do not use the phrases “running a program” and “executing a program” in the same document unless they convey two different meanings. If they convey two different meanings, use them consistently and clarify their definitions in the text or in your glossary.

Similarly, although the following phrases might mean the same thing in English, some readers (and translators) could easily interpret each of them differently:

enter the datatype in the datainput the data

For clarification about when to apply these words, see Section B.5, “Type or Enter,” on page 266.

For more information about correctly using words that are often misused, see Section 3.2, “Terminology Spelling and Usage,” on page 77.

Use words that have multiple meanings carefully. Where possible, do not use such words to mean more than one thing.

Clearly distinguish between different uses of words that can be used as more than one part of speech.

Avoid mixing different uses of the same word in the same sentence.

Wrong: You can use a hub as the hub for your network.

Right: You can use a hub as the central connecting point for your network.

Noun: Run Setup to install GroupWise 8.0.

Verb: When you set up GroupWise 8.0, ensure that…

Noun: If your document is lengthy, localization costs are high.

Verb: Document all options carefully.

Wrong: Click Pause to pause the program.

Right: Click Pause to suspend the execution of your application.


1.15 ContractionsAvoid using contractions. Contractions are unique to English and have no equivalents in most other languages.

1.16 Discriminatory LanguageOur documentation must avoid language that might indicate discrimination of any kind. Be aware that discrimination in language can be subtle. Use care to ensure that our documentation shows respect for all people. Remember also that discriminatory language almost always causes problems for localization and results in extra expense.

Section 1.16.1, “Multicultural User Names,” on page 39 Section 1.16.2, “Cultural Discrimination,” on page 39 Section 1.16.3, “Sexist Language,” on page 40 Section 1.16.4, “People with Disabilities or Illnesses,” on page 41

1.16.1 Multicultural User NamesVary the names used in examples. In a list of sample names, do not use Anglo-Saxon family names exclusively. Use multicultural names, but be careful they do not sound stereotypical or gratuitous. Also, balance the use of male and female names to avoid gender bias.

For a list of approved names recommended by our Localization group, see Section 1.42, “User Names,” on page 64.

1.16.2 Cultural Discrimination Do not use jargon, slang, idioms, or colloquialisms. For example, do not name a server “Snoopy”

or describe a program as “bogus” or “hosed.” Do not use words that carry negative implications. For example, instead of referring to “foreign

developers,” use “international developers.” Do not use examples or samples that reflect a uniquely U.S. outlook. Be aware of things that are

exclusive to the U.S. way of life. For example, if you refer to Social Security numbers, income tax forms, or an office memorandum, you might confuse readers who are not U.S. citizens.

For rules on the presentation of telephone numbers, see “Telephone Numbers” on page 57. Avoid references to holidays, because they are usually country-specific. Also, using the name of

a holiday might have religious undertones. When presenting units of measure, include both metric and U.S. forms when it makes sense to

do so. Be aware, however, of international differences in “standard” measurements. For example, paper sizes are not standard throughout the world, so any reference to an 8-1/2- by 11-inch sheet of paper is culturally specific.


1.16.3 Sexist LanguageSexist language is language that fosters stereotypes about social roles and gender. It often refers to the use of masculine pronouns for gender-neutral nouns. Use the following rules to avoid sexist language:

In general, use the second person in documentation. Speaking directly to the user avoids the need for a third-person pronoun (which, in English, requires gender). When it is impossible to use the word “you,” try to structure the sentence to avoid using a pronoun.

Make the subject plural and use plural pronouns.

Remember to make the appropriate nouns plural in these instances (see the words “system” and “systems” in the preceding example).

Use job titles, not pronouns.

Use a definite or indefinite article (the, a, an) instead of a possessive pronoun (his or her).

If clarity is maintained, use the passive instead of the active voice.

If you must use a pronoun, use “he or she” in place of the generic “he.” Use it sparingly—preferably after exhausting all less obtrusive methods of achieving gender neutrality. But “he or she” is preferable to he/she, sh/e, (s)he, and so forth.

Do not use “they” and “their” as gender-neutral singular pronouns.

Wrong: The administrator should warn users before he shuts down the system.

Right: Warn users before shutting down the system.

Wrong: The administrator is responsible for supporting the users on her system.

Right: Administrators are responsible for supporting the users on their systems.

Wrong: He issues the system password.

Right: The administrator issues the system password.

Wrong: The administrator monitors the installation of the package on her system.

Right: The administrator monitors the installation of the package on the system.

Wrong: He should run a full backup once a week.

Right: A full backup should be run once a week.


For an extended discussion of this topic, see Section B.6, ““Their” as a Gender-Neutral Singular Pronoun,” on page 267.

1.16.4 People with Disabilities or Illnesses Use terminology that emphasizes the person instead of the disability. For instance, use “a

person with xxx” instead of “the disabled person.” Use the following list for terminology to refer to people with disabilities, and to the disabilities themselves.

Avoid the euphemisms “challenged,” “differently abled,” and “special.”

1.17 Emphasis Always try to create emphasis through proper wording and sentence structure before using

formatting tags. Never use formatting to compensate for unclear writing. Use only the tag provided by your authoring tool to provide an emphasis format. Do not use any

other special type style.

Wrong: A user can start their computer by…

Right: Users can start their computers by…

Right: The user can start his or her computer by…

Right: A user can start a computer by…

Use These Terms Instead of

Blind, has low vision, visually impaired Sight-impaired, vision impaired

Has limited dexterity, has motion disabilities Crippled, lame

Deaf, hard-of-hearing, hearing loss Hearing-impaired

One-handed, people who type with one hand Single-handed

People with disabilities The disabled, disabled people, people with handicaps, the handicapped

People without disabilities Normal, able-bodied, regular, healthy

Cognitive disabilities, developmental disabilities

Slow learner, retarded, mentally handicapped

TTY/TDD (to refer to the telecommunication device)

TT/TTD

Person who uses a wheelchair Wheelchair-bound

Person with a seizure disorder Epileptic

Person who has… Victim, stricken by, is affected by

Person of short stature Midget

Is unable to speak Dumb, mute


1.18 File Name Extensions When you use a file name extension in running text and it is not part of a file name, use a period

preceding the file name extension in lowercase and use a monospace font.

Use uppercase with no markup when you use it as an abbreviation or acronym.

1.19 Gerunds and ParticiplesLimit the use of gerunds and present participles in documentation. Their occasional ambiguity can cause problems for localization. A gerund is the “-ing” form of a verb that functions as a noun. A present participle is the “-ing” form of a verb that functions as an adjective.

Use the gerund form of verbs in most headings.

Avoid using gerunds (words that end in “ing”) as subjects or to begin subordinate clauses.

1.20 HyphenationChicago says “Probably nine out of ten spelling questions that arise in writing or editing concern compound words...[whether they are] closed, hyphenated, or open.”

We have several sources to help you find the “authoritative” spelling of compound words. Use them in the following order:

Chapter 3, “Word Choice and Usage,” on page 75. Webster’s

Chicago (16th ed.) Sections 7.77 through 7.85

Examples: .csv file.png file.pdf file

Example: CSV filePNG filePDF file

Wrong: How to Manage the Hardware and Software

Right: Managing Hardware and Software

Wrong: Performance improves after changing these parameters.

Right: Performance improves after you change these parameters.

Wrong: You can change files using the XYZ utility.

Right: Use the XYZ utility to change files.


See Chicago for rules governing hyphenation. The following rules supplement the rules listed there.

Do not add (hard-code) hyphens to create line breaks. Avoid hyphenating the following:

Equations Path names and file names Email and Internet addresses Strings of text the user must enter Product names

Do not use a trademarked term as part of a hyphenated phrase. Rewrite the sentence instead.

When writing out a fraction, use a hyphen.

Hyphenate numbers used with units of measure as adjectives.

You can use a non-breaking hyphen to keep compound words from breaking at the end of a line.

1.21 Modifiers Place modifiers close to the words they modify.

When modifiers are not close to the word they are intended to modify, the sentence can be very confusing for the native English reader as well as for the international reader.

Note the differences in the meanings of the following sentences depending on where the modifier “only” is placed:

Only restart the workstation after you have configured the property page.

Restart only the workstation after you have configured the property page.

Restart the workstation only after you have configured the property page.

Restart the workstation after only you have configured the property page.

Restart the workstation after you have configured only the property page.

Restart the workstation after you have configured the property page only. Limit the number of modifiers for a given word.

Wrong: This is a Windows-specific utility.

Right: This utility runs only on a Windows platform.

Example: Three-fourths of the businesses use GroupWise.

Example: 3-foot cable

Example: 3.5-inch internal hard drive


Compound modifiers can make it difficult, especially for translators, to know which word is modifying what.

1.22 Nouns Avoid using long noun strings. Instead, use a construction that presents the information clearly

and in proper sequence.

Long noun strings create ambiguity because readers and translators do not know which parts of the phrase modify which other parts.

Do not create new words by using nouns as verbs.

When in doubt as to whether a “new” word is valid, consult Webster’s.

1.23 Numbers and MeasurementsUse the following guidelines for numbers and measurements.

Section 1.23.1, “Decimals,” on page 45 Section 1.23.2, “Dimensions,” on page 45 Section 1.23.3, “Equations,” on page 45 Section 1.23.4, “Fractions,” on page 45 Section 1.23.5, “Paper Sizes,” on page 46 Section 1.23.6, “Percentages,” on page 46 Section 1.23.7, “Punctuating Numbers,” on page 46 Section 1.23.8, “Ranges,” on page 47

Confusing: computer spreadsheet program advance information

Improved: advance information on spreadsheet programs for computers

Confusing: paperwork reduction plan implementation meeting

Improved preparation for a meeting to implement a plan to reduce paperwork

Example: User Agent Protocol Data Unit

Example: Remote network monitoring management information base

Example: Distributed foundation wireless medium access control

Wrong: Folder your email message.

Right: Put your email message in a folder.

Wrong: When you present your tables online, iconize them.

Right: When you present your tables online, convert them to icons.


Section 1.23.9, “Units of Measure,” on page 47 Section 1.23.10, “Using Numerals versus Spelled-Out Numbers,” on page 47

1.23.1 DecimalsExpress decimals as numerals. Use 0 as a place holder for decimals between 0 and 1.

1.23.2 Dimensions Use numerals to express dimensions in text, figures, and tables. In text, abbreviate units of measure and use the word “by.”

In tables and figures, abbreviate the units of measure and use the letter “x.”

For more information about abbreviating units of measure, see “Abbreviating Units of Measure” on page 21.

1.23.3 EquationsItalicize the variables in mathematical sequences.

1.23.4 Fractions Use decimal fractions when they are standard.

When you must present a fraction in other than decimal form (for example, in a table), use built-up fractions. Built-up fractions should be used even when an extended character set with stacked fractions is available.

Example: 0.95

Example: 8.5 by 11 in.

Example: 1.5 ft. by 6.2 in.

Example: 8.5 x 11 in.

Example: 1.5 ft. x 6.2 in.

Example: 3x + 5(2a - 7b) = 3x + 10a - 35b

Example: 3.5-inch diskette

Example: 2.5-inch internal hard drive for notebooks and laptops

Example: 0.5-feet USB Type C braided cable

Example: 3.5-inch USB 3.0-compatible external hard drive


When writing out a fraction, use a hyphen.

1.23.5 Paper SizesAvoid references to specific paper sizes.

Paper sizes are not standard throughout the world. For example, in most of Europe the standard paper size is A4, which is slightly longer and narrower than 8-1/2 by 11 inches.

1.23.6 Percentages Use numerals and the percent sign (%) instead of the word “percent.” (No space between the

numeral and the % sign.) If a percentage is used more generically or for emphasis, spell out the numeral and percentage,

such as “A ninety percent solution versus a hundred percent solution.”

1.23.7 Punctuating Numbers Punctuate numbers over 1,000 with a comma every three digits from the right.

However, if you are representing a value within a property or attribute, do not use commas if commas are not used in the standard syntax for the property or attribute.

Do not punctuate computer elements (such as screen sizes, parameter values, and chip designators).

Hyphenate numbers used with units of measure as adjectives.

Wrong: When ½ of the transfer is complete, an acknowledgment is sent to the user.

Right: When 1/2 of the transfer is complete, an acknowledgment is sent to the user.

Example: One-third of the businesses use Linux servers.

Examples: 2,00020,000200,0002,000,000

Example: Change the value from 5000 to 6000 to increase the timeout setting.

Example: 8086803861280 x 1024

Example: 3-foot cable3.5-inch internal hard drive


1.23.8 Ranges When you present a range of numbers in text, use the word “to” between the numbers.

When you present a range of numbers in tables and figures, use an en dash between the numbers, and close up the numbers to the dash.

1.23.9 Units of MeasureFor information about when and how to abbreviate measurements, see “Abbreviating Units of Measure” on page 21.

1.23.10 Using Numerals versus Spelled-Out Numbers Use numerals for whole numbers above nine.

Use numerals for all whole numbers when referring to page numbers, list items, step numbers, or similar items.

Use numerals for ordinal numbers greater than “ninth.”

Use numerals for all numbers in a series when at least one number is greater than nine.

Use a numeral followed by the appropriate unit of measure when referring to numbers in the millions and higher, unless the amount must be stated precisely.

Use numerals for units of measure.

Example: 40 to 80 MB

Example: 40–80 MB

Example: Steve set up 19 workstations this morning.

Example: Mario set up two servers this afternoon.

Examples: page 21Workstation 2Step 6

Example: Henri was able to log in to the server the 10th time he tried.

Example: Olga repeated the sixth step of the procedure.

Example: Jan recorded 5 user names, 4 station addresses, and 19 serial numbers.

Example: 5 million24.5 million24,567,876


Spell out numbers when an amount is approximate.

Spell out numbers that begin a sentence. If possible, rewrite to avoid beginning the sentence with a number.

Present calendar years as numerals, even when they begin a sentence. Spell out the first of two successive numbers in a sentence.

Spell out non-decimal fractions that stand alone (that is, when the fraction does not modify another word).

Example: 64 KB3 ft.

Wrong: 1000s of lines of code

Right: thousands of lines of code

Wrong: one-half, 0.5, or 50%

Right: about half of the parameters were modified

Wrong: one-fourth, 0.25, or 25%

Right: nearly a quarter of the code was corrupted

Example: Ten percent of the files had been copied.

Example: Twenty-two workstations were installed this morning.

Example: About 10 percent of the files had been copied.

Example: The team installed 22 workstations this morning.

Example: thirty 12-inch bolts

Example: eight 6-cylinder engines

Example: three-fourths of the workstations


1.24 Personal, Proprietary, and Private InformationDo not use the real names (first and last), or the phone numbers, extensions, mailstops, passwords, TCP/IP addresses, URLs, user IDs, or email addresses of actual employees or any other “real” people in your screen shots, scripts, contexts, trees, or other examples. Do not use real workstation, server, directory, or directory tree names. Doing so creates both a high security risk and a legal risk.

Replace employee user names with generic names from regions around the world, and replace real workstation, server, and directory names with generic names as well. Do not use trademarked names, celebrity names, names of popular fictional characters, and names of public figures.

For a list of culturally acceptable names for users, see Section 1.42, “User Names,” on page 64. For information about using fictional telephone numbers, see Section 1.34, “Telephone

Numbers,” on page 57. For guidelines and examples of acceptable URLs and domain names, see Section 5.4.12,

“URLs or Domain Names,” on page 161. For information about acceptable IP addresses, see Section 5.4.5, “IP Addresses,” on page 159.

1.25 Personification Avoid personifying products or equipment.

Use verbs that describe machine or software processes accurately.For examples of verbs to avoid and for suggested substitutes, see “Verbs of Personification” on page 126.

Avoid the possessive case when writing about objects. The possessive case personifies the object by implying that it owns something.Frequently, the apostrophe-“s” ending is not essential. For example, “server’s configuration” can become “server configuration” without affecting meaning or clarity.

1.26 PluralsSee Chicago and Webster’s for complete information about plurals. The rules in this section supplement the information found there.

Section 1.26.1, “General Rules for Plurals,” on page 50 Section 1.26.2, “Correct Plurals,” on page 50 Section 1.26.3, “Plural Feature Names,” on page 51 Section 1.26.4, “Plural Nouns,” on page 51 Section 1.26.5, “Plural and Singular Pronouns,” on page 51

Example: A well-managed network is a happy network.

Example: My first Windows computer was so temperamental, the Blue Screen of Death became my screen saver.


1.26.1 General Rules for Plurals If possible, avoid forming the plural of a letter, a numeral, a symbol, or a word referred to as a

word. Instead, rewrite the text to use the singular form.

Use an apostrophe to form a plural only when it is needed for clarity.

Do not use a trademarked term in the plural form. Either rewrite the sentence so the plural is unnecessary, or form the plural with an accompanying generic noun.

1.26.2 Correct Plurals Webster’s allows two plural forms for the words listed here. Use only the following forms:

These words are plural in form but can be singular in meaning:

Confusing: It is often difficult to distinguish ls from 1s.

Clearer: The letter l is often indistinguishable from the number 1.

Confusing: Enter three i’s at the prompt.

Clearer: Enter iii at the prompt.

Confusing: Two *s after a feature indicate that it is currently unavailable.

Clearer: Two asterisks (**) after a feature indicate that it is currently unavailable.

Example: Ensure that the x's are not separated by spaces.

Example: The statement contains too many ifs.

Example: Read this manual to learn the ins and outs of Linux.

Example: CPUs, CD-ROMs, PCs, APIs

Example: 2010s

Wrong: Load the new NLMs during the workstation upgrade.

Right: Load each new NLM during the workstation upgrade.

Right: Load the new NLM programs during the workstation upgrade.

appendixes formulas matrixes

criteria indexes zeros

archives criteria odds

contents data premises


1.26.3 Plural Feature NamesIf a feature name is a plural noun, use a singular verb with it. Feature names are considered proper nouns.

Try to avoid this usage by rewriting the sentence if the information looks unclear.

1.26.4 Plural Nouns Subjects and verbs should always agree. Do not add an “s” in parentheses to a singular noun to create an optional plural. In most cases,

you can use a plural noun with no real loss of meaning. If not, rewrite the sentence to avoid the problem.

Refer to Chicago for rules of agreement for subjects and verbs when the subject is a collective noun.

1.26.5 Plural and Singular PronounsOne of the most basic rules of English grammar is that subjects and verbs should always agree. Pronouns must also agree with noun antecedents. When you substitute pronouns to reference nouns, consider these additional guidelines:

Plural indefinite pronouns always take plural verbs. Use with a clarifying noun or phrase if it improves understanding.

Wrong: When Columns is turned on.

Right: When you turn on Columns.

Wrong: The key(s) you use determine(s) the placement of the cursor.

Right: The keys you use determine the placement of the cursor.

both many

few others

fewer several

Example: Both Red Hat and SUSE Linux distributions are popular with medium-sized businesses.

Example: Others prefer Red Hat derivatives such as CentOS or Oracle Linux.


Singular indefinite pronouns always take singular verbs.

“None” is usually singular, especially when the meaning is “not one” or “not any.” When it means “not any persons or things,” the plural is more common.

Certain indefinite pronouns can take plural or singular verbs, according to the meaning to be conveyed or whether a modifying phrase is plural.

Be mindful of the actual noun you reference. Do not be tempted to change the verb tense by intervening plurals:

anybody enough less nothing

anyone every little no one

anything everybody much somebody

each everyone neither someone

either everything nobody something

Example: Each computer requires a sufficient amount of memory.

Example: Every operating system has different advocates.

Example: Anyone in the airport lobby has free access to the guest Wi-Fi network.

Example: Everybody is allowed to personalize desktop settings.

Example: Of all my court cases, none has been stranger than yours.

Example: The rescue party searched for survivors, but none were found.

all most

any some

more such

Example: All of the data is lost. [Everything is lost.]

Example: All of the servers restart automatically after an upgrade. [Servers restart.]

Example: Each of the computers requires a sufficient amount of memory. [The subject is still “each,” not “computers.”]

Example: Only one of the issues is on the agenda. [The subject is “one.”]


1.27 PossessivesSee Chicago for rules governing the use of possessives. The rules in this section supplement the information there.

Do not use acronyms in the possessive case. Instead, rewrite the sentence.

Do not use a trademarked term in the possessive case. Instead, rewrite the sentence to use the trademarked term as an adjective.

Avoid using possessive terms when they personify inanimate objects.

1.28 Pronouns Keep the pronoun “it” specific, unambiguous, and close to its antecedent. Always follow the pronouns “this,” “that,” “these,” and “those” with a clarifying noun because they

can be ambiguous when used as pronouns.

You should also follow these pronouns with a clarifying noun:

Wrong: The PROM’s location varies from board to board.

Right: The location of the PROM varies from board to board.

Wrong: ZENworks’ features

Right: ZENworks features

Right: the features of ZENworks software

Wrong: Micro Focus’ products are…

Right: Micro Focus products are…

Wrong: This computer’s ability to provide power is too low for its own hard drive’s needs.

Right: In this computer, the power supply is insufficient for the requirements of the hard disk.

Wrong: A procedure cursor is associated with an EXECUTIVE PROCEDURE statement. This allows you to scan multiple rows of data.

Right: A procedure cursor is associated with an EXECUTIVE PROCEDURE statement. This cursor allows you to scan multiple rows of data.

any few one some

another many other your

each neither own

either none several


Ensure that subjects and verbs agree. See Section 1.26.5, “Plural and Singular Pronouns,” on page 51.

Do not use a plural pronoun with a singular noun or pronoun antecedent.

To remain gender neutral, avoid pronouns where possible. See Section 1.16.3, “Sexist Language,” on page 40.

1.29 RecommendationsWhen the action is required, do not use the word recommend or any of its variants.

When you need to recommend a course of action, use language that is appropriate to your audience and the situation you are describing. Several alternate phrases are acceptable:

Use the company name when you want to indicate authoritative advice for product usage.

Use “we recommend” when you want to indicate authoritative advice for best practices.

Simply tell the user what to do, or list something as a fact, when the action or setting is required.

Use “consider” for a course of action that users can or should evaluate.

Wrong: Ask a developer for his or her input.

Wrong: Ask a developer for their input.

Right: Ask a developer for input.

Wrong: A user can change his default settings.

Right: Users can change their default settings.

Right: You can change the default settings.

Example: Micro Focus recommends avoiding the use of all known SSL security protocols that have been compromised.

Example: If you are new to Java, Micro Focus recommends that you choose Apache Tomcat for your Java Server, as it is a lightweight, open-source servlet container.

Example: We recommend that you allow this update.

Example: For security reasons, we recommend that you create a dedicated GroupWise user account.

Example: Create a new user.

Example: Microsoft .NET 4.5.2 is required. Ensure that it is installed on the server before you launch the Installer.

Example: Consider creating a separate administration user or group to manage the software.

Example: Consider which security settings are appropriate for your database.


Use “should” when an action is recommended but optional.

Use “must” when an action is required.

Use passive voice when the agent is either not known or not important.

In general, do not use “it is recommended.” It is neutral, but stilted.

NOTE: In open source documentation, you should use neutral wording for recommended actions instead of authoritative wording. For example, use “It is recommended” instead of “We recommend”. The identity of “we” is difficult to determine and could cause confusion. The use of the company name is unsatisfactory because the open source products might not originate in-house or do not have company technical support to back up the claim.

1.30 RedundancyFor information about redundant words and phrases to avoid, see Section 3.11, “Redundant and Wordy Phrases to Avoid,” on page 128.

1.31 Sentence Structure and ReadabilityWhen you consider sentence complexity, target a readability level of eighth grade.

In general, write simple, direct sentences in subject-verb-object order. Keep the subject and verb as close together as possible.

Avoid complicated dependent clauses. Unless the dependent clause adds significantly to the meaning of the sentence, express it in a separate sentence.

Whenever possible, keep sentences short (under 20 words). Examine long sentences to eliminate noun strings and clarify relationships between the subject, verb, and object. If these relationships are not absolutely clear, they confuse your readers and might cause incorrect translation.

When you instruct the reader to perform an action, use short, direct sentences that begin with imperative verbs.

Avoid ending a sentence in a preposition unless other wordings result in a stilted tone.

Example: You should choose a name that is closely related to the hostname.

Example: You should configure the library immediately after it is created. Do not allow user access until its configuration is complete.

Example: You must install the version of iManager that is included in the software image.

Example: You must mount the domain directory to the local Linux server.

Example: Setting the interval to 0 is recommended if document usage is intensive.

Example: Configuring a secure installation of MySQL is strongly recommended for production environments.


Do not begin a sentence with a coordinating conjunction such as “and,” “but,” “so,” or “or”. Do not begin a sentence with a prepositional phrase, with the following exceptions:

The prepositional phrase provides clarity or orients a reader within a UI.

The phrase is a conjoined clause that begins with if, when, or after. Such phrases often precede the main clause. Follow them immediately with a comma. “If” introduces an action or scenario whose outcome is either unknown or unlikely to

occur. “When” introduces an action or scenario whose outcome is either known or likely to

occur. “After” introduces an action or scenario whose outcome has occurred.

The phrase is “for example,” “in this case,” or “for more information”. Use these phrases at the beginning of a sentence and follow them immediately with a comma.

Sentences with the following words and phrases are likely candidates for revision:

Avoid using gerunds (words that end in “ing”) as subjects or to begin subordinate clauses. Avoid parenthetical material, including content that is offset by em dashes or paired commas. Avoid wordy expressions, such as the following:

Stilted: Scroll through the list until you find the server to which you want to connect.

Better: Scroll through the list until you find the server you want to connect to.

Example: In the Settings group box, select a file from the File list box.

Example: In the menu tree, click the minus sign (-) next to the ALM folder.

actually in fact notice that therefore

again in particular rather this

also lastly since though

however not that there (are, is)


For more examples and alternative wording suggestions, see Section 3.10, “Verbs of Personification,” on page 126.

1.32 Spelling Consult Webster’s for the correct spelling of words. Section 3.2, “Terminology Spelling and

Usage,” on page 77 also has usage guidelines for spelling. Use U.S. spellings and variants. See Section 3.1, “American English,” on page 75.

1.33 Symbols in Text When you refer to a typographic symbol in text, give the symbol name followed by the symbol in

parentheses.

When you refer to an iconic symbol in text, the name for the symbol is optional. Neither the name nor the iconic symbol are presented in parentheses.

1.34 Telephone Numbers Where possible, avoid using telephone numbers. Instead, use wording such as “Contact your

local customer representative,” or use a hyperlink to a web page that lists specific numbers.

a number of in particular not that

cross your mind in the event of note that

do not worry if is equivalent to referred to as

due to the fact that it is not required there needs to be

each and every it is possible think of _______ as having

end result it is up to you to this means that

first and foremost in particular this allows you to

has the ability to it is useful when you finish _______ing

in order to last but not least whether or not

Example: If you need to use the trademark symbol (™), select it from the character palette.

Example: Mark the files to be deleted with an asterisk (*).

Example: Click on the toolbar.

Example: Click the Address Book on the toolbar.


Use the international telecommunications standards for phone and fax numbers. This means that you use spaces as separators instead of using hyphens or parentheses, and that you use the plus symbol (+) for access code numbers outside of North America. Group the numerals according to the format that is commonly used in the area or country where the number originates.

State where the telephone number is valid.

When you list telephone numbers that use mnemonic phrases, add the numerical equivalent for those users whose phones do not have letters.

Remember that toll-free numbers are not available everywhere. State clearly which numbers in your documentation are toll-free and which are not.

Use “ext.” to identify an extension.

Do not use real telephone numbers in your example documents or screen shots.In North America, the entertainment industry often uses 555 2368 as a fictional number, and the telephone industry has specifically reserved 555 0100 through 555 0199 for fictional use. For other locations, check the local phone system’s policy.

1.35 Text ExpansionWhen English is translated into other languages, the text almost always expands. In the following example, note how the English word becomes longer in Italian and must be translated as three words in French.

Example: 1 800 555 3400 [for a number originating in the United States or Canada]

Example: +33 1 55 62 50 00 [for a number originating in France]

Example: +7 495 514 1155 [for a number originating in Russia]

Example: For more information, call 1 800 555 6789 if you are in the U.S. or Canada. If you are calling from another location, call 1 713 555 2345.

Example: 1 800 NETWARE (1 800 638 9273)

Example: This is not a toll-free number.

Example: You will be charged for calls made using the 801 area code.

Example: 1 555 444 3456 ext. 5432

English: Upgrade

Italian: Aggiornamento

French: Mise à niveau


In allowing for text expansion, keep the following points in mind:

Include only essential information. Be concise. Use acronyms and abbreviations sparingly. Be liberal in the use of white space.

The following are examples of text that is especially space-sensitive:

Quick-reference cards Character-based help screens Text in graphics and tables

1.36 “That” versus “Which”Use “that” to introduce restrictive clauses, “which” to introduce nonrestrictive clauses, and “who” to introduce either if humans are involved.

Section 1.36.1, “Restrictive Clauses,” on page 59 Section 1.36.2, “Nonrestrictive Clauses,” on page 59

1.36.1 Restrictive ClausesA restrictive clause is a modifier that is essential to the meaning of the sentence. It is not set off with commas.

For a longer discussion of this rule, including additional examples, see Section B.4, “That and Which,” on page 264.

1.36.2 Nonrestrictive ClausesA nonrestrictive clause is parenthetical and is not essential to the meaning of the sentence. It does not define the word it modifies. To show that the clause can be omitted from the sentence, set it off with commas.

For a longer discussion of this rule, including additional examples, see Section B.4, “That and Which,” on page 264.

Example: The instructions that reside in memory run the program text.

Example: An assembler is a computer language that parses symbolic statements, verifies syntax, interprets semantics, and creates machine language code.

Example: You can view a spreadsheet equivalent, which contains more information than is available in a graph.

Example: The login instructions, which reside in memory, are executed first.


1.37 Such as, and So ForthIt is redundant to use “such as” and “and so forth” together in a sentence. “Such as” implies that some examples follow but there are more that are not listed. “And so forth” says the same but in reverse (some examples are preceding, but there are more that are not listed).

1.38 Time of Day Use the abbreviations “a.m.” and “p.m.” Use lowercase letters with periods but without spaces

between the letters. Do use a space between the time and the time of day designation.

Do not refer to time expressed using the 24-hour clock (such as 0600 or 1800) as “military time.” Use the term “midnight” instead of “12:00 a.m.” or “12:00 midnight.” Use “noon” instead of “12:00 p.m.” or “12:00 noon.”

1.39 Time ZonesPresent acronyms for time zones in uppercase letters without periods.

1.40 Tone, Mood, and VoiceUse the correct tone, mood, and voice in your documentation.

Section 1.40.1, “Tone,” on page 60 Section 1.40.2, “Mood,” on page 62 Section 1.40.3, “Active Voice,” on page 62 Section 1.40.4, “Passive Voice,” on page 63

1.40.1 Tone Strive for a friendly, casual tone, using conversational English when appropriate, but avoid an

overly friendly style. Write as if you were talking to a reader you know, like, and respect.

Wrong: These properties are related to specific features of the stack, such as load balancing, fault tolerance, filtering, and so forth.

Right: These properties are related to specific features of the stack, such as load balancing, fault tolerance, and filtering.

Right: These properties are related to specific features of the stack: load balancing, fault tolerance, filtering, and so forth.

Example: The meeting will be held at 10:45 a.m.

Wrong: E.S.T., M.S.T., G.M.T.

Right: EST, MST, GMT


Never write in a condescending way. Transitions such as “obviously,” “of course,” or “naturally” can irritate a reader. The information might not be obvious at all.

Emphasize positive features instead of deficiencies, and reword negative statements to convey positive, active thoughts.

Avoid using jargon, slang, or unusual contractions.

Do not use humor in your documentation.Technical documentation is not the place for humor. Also, humor is generally culture-specific and can be easily misinterpreted during translation. Many translated jokes can offend the international reader.

Use a positive tone.Avoid using words and expressions that imply lack of confidence in the product or instructions. Following are examples of words or phrases with negative implications that can detract from your writing: Words such as “should” and phrases such as “is designed to” imply a lack of confidence

that the software can perform correctly.

However, “should” is appropriate when you are telling the user about an action that is recommended but optional.

The phrase “try to” sounds negative and implies that the reader will have difficulty performing an action.

Wrong: Of course, if your script’s in the wrong directory, it’ll die.

Right: If your script does not run without errors, ensure that it is in the right directory.

Wrong: GroupWise should open any .txt file.

Right: GroupWise opens any .txt file.

Wrong: The save command is designed to let you update your files.

Right: The save command enables you to update your files.

Right: You should back up your data.

Wrong: When you try to install GroupWise from the server…

Right: When you install GroupWise from the server…


Sentences with the following words and phrases are likely candidates for revision:

Use “must” only in situations where the action is necessary. In the following example, the use of the word “must” is inappropriate because the reader does not absolutely need to follow this step.

In the following example, the use of the word “must” is appropriate because the software does not work if this step is omitted or performed out of order.

Avoid writing in a telegraphic style (omitting articles). This style makes text difficult to understand and translate, and it obscures the function of each word in a sentence.

1.40.2 Mood Use the imperative mood for direct instructions and use the indicative mood for all other

situations. Rephrase hypothetical statements as statements of fact with indicative verbs.

Remember that the “you” in imperatives is usually understood rather than stated.

1.40.3 Active Voice Write in the active voice. Write in the present tense. Avoid other tenses whenever possible.

For more information and examples, see Section 1.43.2, “Verb Tense,” on page 66. Writing in the active voice requires the subject to perform the action.

although ideally through

but impossible try

cannot may typically

designed to probably usually

however should

Wrong: You must start by familiarizing yourself with the terms explained in the following section.

Right: You must first install the XYZ utility.

Wrong: Input volume and directory, browse contents, and select desired file.

Right: Input a volume and directory in the command line; then browse the contents and select the desired file.

Wrong: If more buffers were needed, you could tune the number of directory cache buffers yourself…

Right: If more buffers are needed, you can tune the number of directory cache buffers yourself…

Wrong: You must make a backup before running the program.

Right: Make a backup before running the program.


The imperative mood is closely linked to the active voice. Use it to shorten and simplify instructions.

1.40.4 Passive Voice In general, use active voice instead of passive.

Active voice is usually more concise and more forceful than passive voice, and it emphasizes the doer of the action.

Use passive voice when it is important to emphasize the receiver of the action rather than the doer.

Use passive voice when the agent is either not known or not important.

1.41 Trademarks Micro Focus trademarks and registered trademarks are noted on the Legal page of the Micro

Focus websites. Instead of repeating it, the Legal Notice provides the URL to the Legal page. Do not add trademark or registered trademark symbols anywhere in the body of the

documentation. Do not add third-party legal notices in product documentation. Third-party legal notices for

software that is included in the product are maintained by Engineering in the Inbound Technology License System (ITLS). They export a report for a product release and add it to the product build.

Wrong: The scroll box can be used as a navigation tool.

Right: Use the scroll box as a navigation tool.

Wrong: You should apply the changes by clicking OK.

Right: Click OK to apply the changes.

Weak passive: The network must be updated by the administrator.

Strong active: The administrator must update the network.

Weak passive emphasis on doer:

TTS does not protect files that the application does not organize into discrete records (the way a word processor organizes files).

Strong passive emphasis on receiver:

Files that are not organized into discrete records (such as word processing files) are not protected by TTS.

Weak active: The computer sends your output to the nearest printer.

Strong passive: Output is sent to the nearest printer.


1.42 User NamesVary the names used in examples. In a list of sample names, do not use Anglo-Saxon family names exclusively. Use multicultural names, but be careful they do not sound stereotypical or gratuitous. Also, balance the use of male and female names to avoid gender bias.

The following are sample names approved by the Localization group for use in our documentation:

Language/Culture Masculine Name Feminine Name Surname

Chinese Jian-guoMingZhi-Wei

Mei-huaLing-lingXiao-yan

LiLinWangZhangZhao

French AndréHenriLucMauricePierre

ClaireMarieNathalieStéphanieVéronique

BertrandDeschampsDuboisLamottePicard

German AlbertMarkusThomas

BrigitteGudrunSusanne

HauserKurzMüllerSchneiderWagner

Indian AnandDeepakRahulShankar

AmritaDivyaPreethiPriyaShradhaSwathi

GuptaNayarPathakReddySenTalwarVerma

Italian AntonioGiovanniLucioMarioPasquale

AngelaCarlaPaolaSofiaTeresa

BianchiClementiFranchiManciniRivoli

Japanese FumioHiroyukiKenjiTakeshiYoshito

HirokoMichikoRieSaoriYumi

FujisawaKomatsuSatoTanakaYamaguchi

Korean Chang-sickDong-kyuHyun-soo

Jee-sooMee-kyoungSon-hee

ChoiChongHanKimPark


1.43 VerbsFor information about verbs to use in procedures, see “Verbs for Use in Procedures” on page 202.

For information about verbs to use in avoiding personification of products and equipment, see “Verbs of Personification” on page 126.

For additional usage guidelines, see Chapter 3, “Word Choice and Usage,” on page 75.

For a discussion of using “type” versus “enter,” see Section B.5, “Type or Enter,” on page 266.

For information about how the verb “using” can sometimes create antecedent problems, see Section B.8, “Using the Word “Using” in Documentation,” on page 270.

1.43.1 Verb PhrasesPhrasal verbs are combinations of a verb and an adverb (or preposition) that function as a single verb (such as “turn on” or “set up”).

Avoid separating the two elements of phrasal verbs.

In headings and titles, capitalize both words in a phrasal (compound) verb.

Portuguese (Brazilian) DanielPauloRicardo

RejeneSilviaTeresa

AlmeidaPereiraViana

Russian IvanKonstantinMaximMikhailNikolai

IrinaLubaKatarinaOlgaTatiana

Borodin (masc.)/Borodina (fem.)

Ivanov/IvanovaKlimov/KlimovaLebedev/LebedevaPetrov/Petrova

Spanish CarlosJoséJuanManuelMateo

CarmenIsabelJosefaLuisaMaría

GarcíaGonzalezMartinezPerezRodriguez

Taiwanese Wen XiongXiao HuiYing Ming

Huei MeiJia LiXiao Men

ChangChenLiuMaWang

Language/Culture Masculine Name Feminine Name Surname

Wrong: Turn Block off…

Right: Turn off Block…


Use direction sparingly. Review your sentence to find if it can be phrased without direction.

Some dialog boxes feature Move Up and Move Down buttons that rearrange the order of items in a list. In these cases, use the words “up” and “down” instead.

Avoid “left-hand” or “right-hand” directions. Use “left” or “right” instead.

1.43.2 Verb Tense Use the simple present tense almost exclusively.

Unless there is a very clear shift in time from past to present or a very clear reference to the future, describe a series of actions in the present tense.

State perpetual cause-and-effect relationships (every time x happens, y occurs) in the present tense.

Use future tense only when anticipating an event that is yet to happen.

For additional examples, see Section B.9, “Verb Tense,” on page 271.

Example: Setting Up the Workstation

Example: Logging In to the Network from a Client Workstation

Wrong: Scroll down to the variable xyz.

Right: In the Code Editor, scroll to the variable xyz.

Wrong: The password contained an invalid character.

Right: The password contains an invalid character.

Wrong: When you select this command, GroupWise will open the text files.

Right: When you select this command, GroupWise opens the text files.

Example: In the next lesson, you will learn how to write a macro.

Example: After you finish this lesson, you will know how to write macros.


2 2Punctuation

Our documentation follows the basic punctuation rules found in Chicago. This section lists exceptions and variations, and reiterates some of the Chicago rules.

Section 2.1, “Ampersand,” on page 67 Section 2.2, “Braces or Curly Brackets,” on page 67 Section 2.3, “Brackets,” on page 67 Section 2.4, “Colons,” on page 67 Section 2.5, “Commas,” on page 68 Section 2.6, “Dashes,” on page 69 Section 2.7, “Ellipsis Marks,” on page 70 Section 2.8, “Exclamation Points,” on page 70 Section 2.9, “Hyphens,” on page 70 Section 2.10, “Italics,” on page 70 Section 2.11, “Parentheses,” on page 71 Section 2.12, “Periods,” on page 71 Section 2.13, “Quotation Marks,” on page 72 Section 2.14, “Semicolons,” on page 72 Section 2.15, “Slashes,” on page 72

2.1 AmpersandDo not use the ampersand (&) in documentation unless you are referring to an interface item that uses it.

2.2 Braces or Curly BracketsBraces {}, also known as curly brackets, are used in various programing languages. Do not use braces in documentation unless they are used in an interface, command syntax, or program code examples.

2.3 BracketsThe word bracket always means a square bracket [ ], never a parenthesis. Do not use brackets in documentation unless they are used in an interface, command syntax, or program code examples.

2.4 Colons Use a colon after introductory phrases that introduce an example or list. Introductory phrases

include “for example,” “for instance,” “the following,” and similar phrases.

Punctuation 67

Do not capitalize the first word following a colon in running text unless that word would normally be capitalized anyway.

Include only one space after a colon in running text.

2.5 CommasFollow the rules for commas given in Chicago. This section lists exceptions and variations, and reiterates some of the Chicago rules.

Section 2.5.1, “In a Series,” on page 68 Section 2.5.2, “With Compound Predicates,” on page 68 Section 2.5.3, “With Conjunctive Adverbs,” on page 69 Section 2.5.4, “With Nonrestrictive Clauses,” on page 69 Section 2.5.5, “With Subordinating Conjunctions,” on page 69

2.5.1 In a SeriesUse a serial comma (or Oxford comma) in lists of things.

Use a comma to separate all items in a series of three or more items, unless any of the items is a phrase containing commas. In this case, use semicolons to separate the items.

Present serial commas in normal type even if the items in the series are in boldface or italic type. The comma should be placed outside the tagged text.

2.5.2 With Compound PredicatesDo not separate the elements of a compound predicate with a comma unless the compound predicate has more than two elements. See Chicago for a complete explanation.

Example: You can do one of three things: restart your computer, save the file with a different name, or close your application without saving your changes.

Example: The Setup program installs two files: autoexec.bat and nwconfig.sys.

Example: The Setup program installs two files: autoexec.bat and nwconfig.sys.

Wrong: Three types of messages include alerts, announcements and account or email notifications.

Right: Three types of messages include alerts, announcements, and account or email notifications.

Commas: Write down the name of the remote host, your user name, and your password.

Semicolons: Write down the name of the remote host; your user name, which is the name you use to log in to that host; and your password.

Wrong: Remove the old adapter from the slot, and insert the new adapter.

Right: Remove the old adapter from the slot and insert the new adapter.

68 Punctuation

2.5.3 With Conjunctive AdverbsDo not use a comma before a conjunctive adverb that joins two complete sentences; use a semicolon.

For more information, see “Semicolons” on page 72.

2.5.4 With Nonrestrictive ClausesUse commas to set off nonrestrictive clauses.

A nonrestrictive clause is a parenthetical clause that can be removed from the sentence without changing the meaning.

For more information about restrictive and nonrestrictive clauses, see Section 1.36, ““That” versus “Which”,” on page 59.

2.5.5 With Subordinating Conjunctions Always use a comma after an introductory subordinating conjunction.

A subordinating conjunction that comes at the end of a sentence generally does not require a comma before it.

2.6 Dashes Use dashes sparingly. Use the facility provided by your authoring tool to insert the correct dash (em or en). If your authoring tool does not support dashes, use two hyphens. Use em dashes (—) to set off amplifying, explanatory, and digressive elements in sentences.

Em dashes indicate a greater break in continuity than do parentheses. They are often used to interrupt—abruptly—a sentence.

Right: Remove the old adapter from the slot, insert the new adapter, and close the lever.

Wrong: Text you cut and paste retains its properties, however if you use the Copy command, no properties are retained.

Right: Text you cut and paste retains its properties; however, if you use the Copy command, no properties are retained.

Example: Micro Focus, headquartered in the United Kingdom, is an industry leader.

Example: PlateSpin Migrate starts a discovery job, which you can monitor in the Jobs view.

Example: Although the server abended, no data was lost.

Example: No data was lost although the server abended.

Punctuation 69

Use an en dash (–) for a minus sign and to express a range of numbers in tables and figures, but use the word “to” to express a range of numbers in running text.

2.7 Ellipsis Marks The ellipsis mark (…) is a set of three spaced periods that indicate where words are left out in

text. For usage rules and examples, see Chicago. Use ellipsis marks sparingly, if at all. They are seldom used in technical documentation. If a menu item contains an ellipsis in the interface, do not include the ellipsis in running text.

For information about using ellipses in command presentation, see Section 5.7.4, “Long Elements (Multi-line),” on page 169 and Section 5.7.5, “Repeated Elements,” on page 170.

For information about using ellipses in computer input, see Section 5.11, “Source Files,” on page 172.

2.8 Exclamation PointsDo not use exclamation points!

2.9 Hyphens Consult Webster’s for the correct spelling of potentially hyphenated words. Section 3.2,

“Terminology Spelling and Usage,” on page 77 also has usage guidelines for spelling of compound nouns, adverbs, and adjectives.

For information about using hyphens, see “Hyphenation” on page 42.

2.10 Italics Italicize titles of complete works, including guides, readmes, release notes, quick starts,

knowledge base articles, and technical white papers.

Wrong: You need 40-80 MB for this program.

Right: You need 40 to 80 MB for this program.

Right: It was –20° today.

Wrong: Click File > Open… to find the file you want.

Right: Click File > Open to find the file you want.

Example: For information about known issues, see the Identity Manager Release Notes.

70 Punctuation

Italicize the variable names that represent replaceable options in commands.

Italicize words for emphasis. You can alternatively surround the word in quotation marks. Use emphasis sparingly. Words used as words; that is, when you refer to the word itself, and not the thing it

represents.

Words used in some special way.

Letters of the alphabet referred to as letters. Italicize only the letter itself for plural or possessive forms.

2.11 ParenthesesFor rules about using parentheses, see Chicago.

2.12 Periods Use only one space between a period and the beginning of a new sentence. For rules about using periods in time and time zone references, see “Time of Day” on page 60

and “Time Zones” on page 60.

For all other rules about using periods, see Chicago.

Example: nexm [user] [options…]

Where options can be

[clear | read | stop | write][locate | restore][draw | store | verify | wait][erase | print | reset]

Example: A transmission is asynchronous if the receiver expects a sequence of operations is irrespective of time.

Example: Set up a PlateSpin Protect security group to enable its members to carry out specific workload protection tasks on specified workloads.

Example: Use Search to locate cluster resources that start with the specified alphanumeric characters.

Example: Use a wildcard to copy all files from the reports folder that start with the letter s to the C:\temp folder:

copy C:\reports\s* C:\temp

Punctuation 71

2.13 Quotation MarksSee Chicago for rules about using quotation marks. The rules in this section supplement the information found there.

Put semicolons, colons, and dashes outside quotation marks. Put question marks and exclamation points outside quotation marks unless they are part of the

quotation. Put periods and commas outside the closing quotation mark if putting it inside the quotation mark

can create problems for the user or where the authoring tool prevents it. In this case, enclose only punctuation that appears in the original material. See Chicago (16th ed.) Section 6.9 and 7.75. Content that requires such clarity include the following: pieces of code command examples text to be typed in a text box file names URLs Cross-reference elements created in the authoring tool that automatically enclose the cross-

referenced heading text in quotation marks Do not use quotation marks to attach emphasis or draw attention to unusual words or usages.

Instead, phrase the sentence so that the meaning is clear.

Use quotation marks to set off words used as words.

Use quotation marks to set off words used as examples in running text.

When your authoring system permits, use smart quotes (curly quotes) in running text. Use straight quotes to enclose literal strings in syntax examples or code samples.

2.14 SemicolonsAvoid using semicolons. Instead, concentrate on writing short, concise sentences. If you need to use semicolons, follow the usage guidelines in Chicago.

2.15 Slashes Avoid using forward slashes (/) and backslashes (\) except in computer terms, paths, URLs, and

syntax.

Wrong: To get a “big picture” understanding of Linux, see Chapter 2.

Right: For a general understanding of Linux, see Chapter 2.

Example: To use the word “word” in running text, you must…

Example: The apostrophe-“s” ending is often not essential. “Server’s configuration” can become “server configuration” without affecting meaning or clarity.

72 Punctuation

For information about using slashes in computer terms and syntax, see Chapter 5, “Computer Elements,” on page 151.

Avoid using the “and/or” construction. When you write out a URL, always use forward slashes unless the URL must use backslashes. When you write out path names, use backslashes unless the software you are documenting

requires forward slashes.

Terms: CAD/CAMI/Oclient/server

Paths: f:\public\homeURLs: https://<server-ip-address>/migrate

Punctuation 73

74 Punctuation

3 3Word Choice and Usage

This section describes word choice and usage guidelines. See Appendix D, “Product Terminology,” on page 275 for terminology and usage guidelines that are product specific.

Section 3.1, “American English,” on page 75 Section 3.2, “Terminology Spelling and Usage,” on page 77 Section 3.3, “Latin Terms and Abbreviations,” on page 113 Section 3.4, “Abbreviations for Units of Measure,” on page 114 Section 3.5, “Acronyms for Common Technical Phrases,” on page 115 Section 3.6, “GUI Terminology,” on page 123 Section 3.7, “Command Line Terminology,” on page 123 Section 3.8, “Pronouns That Need a Clarifying Noun,” on page 124 Section 3.9, “Transitional Words and Phrases,” on page 125 Section 3.10, “Verbs of Personification,” on page 126 Section 3.11, “Redundant and Wordy Phrases to Avoid,” on page 128 Section 3.12, “Potentially Troublesome Words,” on page 133

3.1 American EnglishMicro Focus documentation uses American English for spelling, hyphenation, and usage to promote consistency across our products.

“British English and American English” on page 75 “Colloquialisms” on page 77 “Idioms” on page 77 “Jargon” on page 77 “Slang” on page 77

3.1.1 British English and American EnglishThe following table displays the British expression and the American equivalent. Use the American English to promote consistency across the documentation sets.

British Expression American Expression

amend modify

amidst amid

amongst among

as for same as for

co-operative cooperative

Word Choice and Usage 75

details of details on

disc disk

exclamation mark exclamation point (but question mark)

favour favor

for further information for more information

grey gray

irrespective regardless

-ise* -ize

-isation* -ization

highlit highlighted

in one go in one try

in the list on the list

licence license

maths math

next but one (no general equivalent; re-word it)

no-one no one

note down write down

on the path in the path

-our* -or

presently (at the present time) currently, now

presently (soon) soon

-re* -er

round around

rub out erase

semi-colon semicolon

spelt spelled

star asterisk

thousand million billion

tick check

whilst while

* In these entries, the US and UK spellings differ only when the letters shown form a complete syllable, used as a suffix. Thus color, emphasize; but flour, wise, concise, advise.

British Expression American Expression

76 Word Choice and Usage

3.1.2 ColloquialismsDo not use colloquial vocabulary. The following table provides some examples:

3.1.3 IdiomsDo not use idiomatic expressions. Customers from other countries, cultures, or native languages might not be familiar with that phrase and can mistake its meaning. Reword the sentence without using idioms to make your meaning clear.

3.1.4 JargonAvoid using cultural, legal, foreign, and technical jargon. Ensure that terminology is appropriate to the industry and audience. When you feel technical jargon is necessary but your audience might not understand it, define your term on first use with a plain language translation that is concise and accurate, or define the term by creating context for it in the sentence.

3.1.5 SlangDo not use slang.

3.2 Terminology Spelling and UsageFollow these spelling and usage guidelines for specific words and phrases. For more spelling and capitalization guidance, see Webster’s.

NOTE: Terminology in heritage products might conflict with modern usage guidelines. It is not necessary to update documentation and product UI only for this purpose. In these cases, ensure that the terminology used in documentation is compatible with the product and consistent within the doc set.

Colloquial Expression Recommended

blue screen of death (or BSOD) Windows Stop error

daily basis daily

due to the fact that because

for the most part usually

in recent years recently

In the event that If (or When)

past history history

with regard to about


A to Z Access

Sym/# A B C D E F G H I

J K L M N O P Q R S

T U V W X Y Z

Word or Phrase Usage Guideline

Symbols and Numbers

& / ampersand Do not use the ampersand in documentation unless you are referring to an interface item that uses it.

+ / plus sign (+) Use the wording “Click the plus sign (+)” instead of “Click +” or “Click the plus sign.”

10BASE2 Use this capitalization.

10BASE5 Use this capitalization.

10BASE-F Use this capitalization and hyphenation.

2-byte font Use “double-byte font” instead.

56 bytes long Use “56 bytes” instead.

32-bit64-bit

Hyphenate for adjectives.

A

abort Use “cancel” or “exit” instead.

above Do not use as a locator reference, because such references might change with printed pagination or be unavailable in a shared or help usage. Such references are meaningless in most online documentation. If it is in the same topic, use “preceding” instead. If it is in a different topic, create a cross-reference link instead.

When you instruct users to use the last in a series of versions, patch updates, or service packs, use the word “later” or “latest” instead of “higher,” “greater,” above, or “newer.”

absolutely This adverb is almost always redundant (as in the phrase “absolutely essential”). Avoid using it.

accelerator key In the Windows environment, use “keyboard shortcut” instead.

account limits Use “account restrictions” instead.

ACKacknowledgment

A code sent by the destination station to the origination station in a TCP handshake. Note capitalization (do not present as “Ack” or “ack”). Do not substitute “acknowledgment” for ACK.

active window The open window where the user is currently entering information or performing an action.

actual fact Use “fact” instead.

actually The primary English meaning of “actually” is “existing in fact or reality.” However, in most European languages, its primary meaning is “current” or “present.” Avoid using it or be more specific.


adapter Do not use “adapter board” for this term.

add-in

add in

Noun and adjective: hyphenated.

Verb: two words.

add-on

add on

Noun and adjective: hyphenated.

Verb: two words.

address When you refer to addresses, be specific (for example, “base I/O address,” “Ethernet address,” “network address,” and “IRQ address”).

address book Two words.

administrator Be specific in the first instance of any discussion: “network administrator,” “system administrator,” “domain administrator,” “local administrator,” and so on. Thereafter, this term can be shortened to “administrator” if the administrator type is clear from the context. Where you address multiple administrator types in different areas of the discussion, be specific in each context.

agent Use initial capitals when it refers to a specific agent; use lowercase when it is generic.

Example: Restart the Message Transfer Agent.Example: NIMS has twelve agents.

alarm log Lowercase.

alert Do not use “alert” if you mean “alert message.”

all of This is permissible before a pronoun (as in “all of them”). The “of” is usually unnecessary before a noun, unless the construction uses a partitive genitive for good stylistic effect. Try to use “all the” as the intensifier instead.

all-routes broadcast frame

Use a hyphen and lowercase.

all-routes explorer frame

Use a hyphen and lowercase.

alphabetic Use “alphabetic” when your refer to things related to or using the English alphabet. Compare with alphabetical order.

alphabetical order Use “alphabetical” when you refer to arranging a list of things in the order of the letters of the English alphabet. Compare with alphabetic.

alphanumeric One word, no hyphen.

also This adverb is often redundant (as in the phrase “and also”). Avoid using it.

Alt Use this form when you refer to the Alt key.

alternatealternative

Do not use “alternate” when you mean “alternative.” “Alternate” (verb) means “to occur in successive turns” or “to pass from one state, action, or place to a second, and back to the first, and so on indefinitely.” “Alternative” (noun) means “the choice between two mutually exclusive possibilities.”Do not use “alternative” when you mean “other,” “new,” “fresh,” or “revised.”



a.m. Present time of day abbreviations in lowercase, with periods but without spaces between the letters. Do not spell out the abbreviation.

Example: The meeting will be held at 10:45 a.m.

Use the term “midnight” instead of “12:00 a.m.”

and/or Avoid this construction. Whenever possible, use just “and” or “or.”

answer Do not use “give” or “to” (as in the phrase “give answers to”) with this verb. “Answer” or “answers” is sufficient.

answer automatically Verb: two words.

For the noun or adjective, use “autoanswer.” Do not use “auto-answer.”

API Use this term instead of “application program interface.”

appears / displays The verb “display” is transitive, which mean that it needs a direct object. “Appears” does not need a direct object.

Wrong: The message displays.Right: The message appears.Right: The message is displayed.

appendixes Plural of appendix.

application In the Common Desktop Environment (CDE), the preferred term is “software application,” and the term is sometimes used interchangeably with “product.”

application programming interface

Use “API” instead.

archive To copy files to a storage device (such as a diskette, magnetic tape, or optical disk) for long-term storage.

See also back up / backup.

archival copy The legal term for the copy of software a user makes for safekeeping. Do not use “backup copy” as a synonym for “archival copy.”

See also back up / backup.

area address Use lowercase, not initial capitalization.

armed emphasis: Use “ready emphasis” instead.

ARPANET Use all capitals.

as, since, for Use “because” to express a cause or reason. Avoid using “since,” “for,” and “as” when “because” will convey your meaning effectively.

Ambiguous: Do not place the diskettes in a location with temperatures above 80 degrees, since they will be damaged.

Ambiguous: Do not place the diskettes in a location with temperatures above 80 degrees, as they will be damaged.

Precise: Do not place the diskettes in a location with temperatures above 80 degrees, because they will be damaged.

assure To reassure or put at ease. Do not confuse this term with “ensure” or “insure.”

asynchronous transmission

Use the complete word in text. Abbreviate to “async” only in tables and figures, or if used as such in a proper noun.



audible cue Use “alarm” instead.

audit data file Use lowercase.

audit file Use lowercase when it refers to a system log file.

audit history file Use lowercase when it refers to a system log file.

autoanswer Noun or adjective: one word, no hyphen. Do not use “auto-answer.”

For the verb, use “answer automatically.”

autodial Noun or adjective: one word, no hyphen. Do not use “auto-dial.”

For the verb, use “dial automatically”

autodiscoverauto-discover

Do not use. Use “discover” or “discover automatically” instead.

autoload Noun or adjective: one word, no hyphen.

For the verb, use “load automatically.”

automount

auto-mount

Do not use. Use “mount” or “mount automatically” instead.

autopartition Noun or adjective: one word, no hyphen.

For the verb, use “partition automatically.”

.avi file In running text, use a period preceding the file name extension (.avi) and mark it up with the Filename element, or use the abbreviation “AVI file.”

available Use “available” and “unavailable” in reference to commands or options that are in a usable or unusable state. Use “dimmed” to describe the appearance of an unavailable command or option.

avoid Do not use the phrase “try to” as a preface to this verb.

awk Note capitalization; awk is a UNIX command (case sensitive).

B

back-end Noun or adjective: one word, hyphenated.

backbone One word.

Backpanel display Use capitalization as shown.

backslash One word.

Backspace Use this form when you refer to the Backspace key.

backup

back up

Noun or adjective: one word. A duplicate of data (file, directory, volume), copied to a storage device (floppy diskette, cartridge tape, hard disk). A backup can be retrieved and restored if the original is corrupted or destroyed.

Verb: two words. To periodically make duplicate copies of important files as insurance against disk failure, power outage, or accidental deletion of files.

See also archive and archival copy. Do not use “backup copy” as a synonym for “archival copy.”

Bash Proper noun.



basic input/output system

“BIOS” is the preferred term.

baud Hyphenate when used as part of a modifier that precedes a noun, as in “2400-baud modem.”

because of / due to Use “because of.”

Wrong: The feature unlocks all passwords that were locked due to an intruder alert.Right: Because of the need to provide different configurations, new policies have

been added

Beta / beta Use initial caps when you refer to a specific beta release, but use lowercase when it is generic.

Example: The Beta 1 release will be available on June 30.Example: This beta release adds new features.

below Do not use as a locator reference, because such references might change with printed pagination or be unavailable in a shared or help usage. Such references are meaningless in most online documentation. If it is in the same topic, use “following” instead. If it is in a different topic, create a cross-reference link instead.

When you instruct users to use the previous version in a series of versions, patch updates, or service packs, use the word “earlier” instead of “lower,” “lesser,” below, or “older.”

.bfp file In running text, use a period preceding the file name extension (.bfp) and mark it up with the Filename element, or use the abbreviation “BFP file.”

bidirectional One word, no hyphen.

big-endian Use “high-low” instead.

.bil file In running text, use a period preceding the file name extension (.bil) and mark it up with the Filename element, or use the abbreviation “BIL file.”

binary zero Spell out in text, but use as a numeral in figures and tables.

BIOS Use this term instead of “basic input/output system.”

.bip file: In running text, use a period preceding the file name extension (.bip) and mark it up with the Filename element, or use the abbreviation “BIP file.”

bitmap One word, no hyphen.

.bix file In running text, use a period preceding the file name extension (.bix) and mark it up with the Filename element, or use the abbreviation “BIX file.”

block Use “select” instead.

Bluetooth Proper noun.

board name Two words.

bogus Do not use.

bold 1. In documentation, do not use “bold” when you mean “boldface.”

2. In user interface design, use “Bold” instead of “Bold Font” or “BoldFace” as a feature name to turn on and off the boldface font attribute. (Note initial capitalization of feature names.)



boot / reboot To start or restart a server or workstation in a Linux or UNIX environment.

Use “start” or “restart” instead of “boot” or “reboot” when you are referring to starting a computer in a Windows environment.

See also start / restart.

boot disk Also called a “startup disk.” Use the term preferred in your technology, and be consistent within a given set of documentation.

boot loader Two words.

BOOTP Use all capitals as indicated. Do not present as “bootp” or as “BootP.”

BOOTP relay agent Do not use “DHCP relay agent,” “DHCP forwarder,” or “BOOTP forwarder” as synonyms for this term.

border The boundaries of a window or dialog box.

Example: When the Select Options dialog box is active, the border flashes.

box When possible, use just the name of the option or dialog box area instead of calling it a “box,” “group box,” or “field.”

Wrong: In the Mail and Phone box, select an option.Right: Select a mail and phone option.

See also field and group box.

bpi Bits per inch. Use lowercase.

broadcast To send a message to all users currently logged in to the same network.

browser frame Can be shortened to “frame” after first occurrence.

Btrfs file system Proper noun, not an acronym. Pronounced “butter-eff-ess” by its creator.

bug / defect Use this term if it is appropriate for your software or platform. However, remember that we should maintain a positive tone, especially in user documentation. We usually avoid discussing defects, limitations, and bugs except in Readmes, Release Notes, and Troubleshooting documentation.

For information about displaying defect numbers in Release Notes, see Section 16.4, “Known Issues,” on page 226.

burst Do not use as a verb to describe data transfer.

burst mode Ensure that your context makes clear which meaning this term refers to. (Use the term Packet Burst protocol somewhere in the discussion before using this term, if that’s the kind you are writing about.)

buses Use both as a plural noun and as a verb. This spelling is listed first in Webster’s for both forms.

button A control in a window or dialog box that initiates or cancels an action. Each button is labeled with the action it initiates. In most cases, you can just use the label text to refer to a button (“Click OK “ instead of “Click the OK button”).

For more information, see “Graphical User Interfaces” on page 152.

C

CA Abbreviation of certificate authority.



cable together Use “cable” instead.

calendaring Use “scheduling” instead.

callback Adjective: one word.

can, might, may

Use “can” to express ability, “might” or “could” to show a possibility, and “perhaps” to express a subjunctive mood. Use “may” only where permission is sought or for a legal statement.

Wrong: You may change the settings later.Right: You can change the settings later.Right: The elements might still be resident in memory.

canceledcancelingcancellation

One L for “canceled” and “canceling;” two Ls for “cancellation.”

canonicalize Use “fully distinguish” instead, unless describing a constant or variable that uses “canonicalize” in its name.

capture filter Do not use “prefilter.”

case-insensitivecase insensitive

Compound adjectives should be hyphenated when they come before the word they describe. However, when they come after the word they describe, they do not use a hyphen. (For an explanation of this apparent inconsistency, see Chicago, 16th Edition, 7.81.)

Following this rule, both of the following sentences are correct:

Example: The Windows login requires case-insensitive user names.Example: The Windows user name is case insensitive.

If both usages occur in the same paragraph or procedure, use one convention or the other to avoid the appearance of inconsistency.

Do not use “case-independent.” Another wording might be “case is not important.”

case-sensitivecase sensitive

Compound adjectives should be hyphenated when they come before the word they describe. However, when they come after the word they describe, they do not use a hyphen. (For an explanation of this apparent inconsistency, see Chicago, 16th Edition, 7.81.)


Example: Use a case-sensitive password.Example: The password is case sensitive.

If both usages occur in the same paragraph or procedure, use one convention or the other to avoid the appearance of inconsistency.

caveat Use as necessary to warn readers of issues that could create problems.

Compare with prerequisites, requirements, guidelines, and considerations.



CCITT Replace the abbreviation “CCITT” with “ITU-T (International Telecommunication Union, Telecommunication Standardization Sector)”. On the first instance of ITU-T, spell out the organization and sub-organization names, separate the names with a comma, and enclose the names in parentheses; then follow this construction with the phrase “previously CCITT” separated from the sentence by commas.

Example: Refer to the ITU-T (International Telecommunication Union, Telecommunication Standardization Sector), previously CCITT, Recommendation X.25, before setting this parameter.

CD / CD-ROM Use CD instead of CD-ROM, unless you need to differentiate between music CDs and data storage CD-ROM disks.

central processing unit Always use the abbreviation CPU. Do not use the spelled-out term.

central time This term should be presented in lowercase, as should “central daylight time” and “central standard time.”

certificate authority Although this term is also called “certification authority“ or ”certifying authority,” “certificate authority” is the preferred term.

certification authority Use “certificate authority” instead.

cheaper-net Use “thin Ethernet” instead.

check The word “check” is potentially confusing, because it can mean both “place a check mark” and “look at.” Use words such as “verify” or “review” when you want the user to look at something.

Example: Review your selections to ensure that they are correct.Example: Verify that you have the correct information in all of the fields.

check box Two words. Use "select" or "deselect" as the verbs.

A standard Windows control that displays a setting that can be either on or off. Check boxes are not mutually exclusive, meaning that a group of them can all be active at the same time. See also option button.

You should usually refer to check boxes by their label names instead of calling them "check boxes." For example, "select Outline" instead of "select the Outline check box." If you must refer to them by the generic name, call them "check boxes," not "boxes."

Wrong: Check the box.Wrong: Mark the check box.Preferred: Select Update.Alternate usage if necessary for clarity: Select the Update check box.

checklist One word.

check mark The symbol that appears in a check box to indicate it is active.

Example: To find out whether Snap is turned on, display the Graphics menu and look for the check mark.

chipset One word.

choose Use “select” or “click” instead.

Chromebook Proper noun.

A laptop running the Linux-based Chrome OS as its operating system.



clean-up

clean up

Adjective: hyphenate unless it is part of a proper name, as in “Cleanup Options.”

Verb: two words, unless it is part of a well-established feature name such as Cleanup Options.

Clear Recommended for user interface design as a feature name for “erasing” the window contents. For example, “Use Clear to delete all contents of the active window.” Clear is especially used in Graphics editors. Do not use as a button label for removing items from a list; use “Delete” instead.

In documentation, Microsoft uses “clear” as the opposite of “select;” however, we use “deselect” for that purpose.

Clear To Send All three words have initial capitalization when used as an expansion of the acronym CTS.

click To position the mouse pointer on an element of the interface and then press and release the mouse button.

Do not use with “on,” as in “click on.”

Client / client Use lowercase unless you are referring to a trademarked term (such as Novell Client) or part of a proper name (such as Windows 10 Client Hyper-V).

client/server Note the slash. Do not use a hyphen, as in “client-server.”

clip art

clip-art

Noun: two words.

Adjective: hyphenated.

clipboard One word. When you refer to a feature in an operating system, use lowercase.

clone Avoid using this term to describe a device that doesn’t look like the original but works like it. Use “compatible” instead.

close To remove a window or document from the desktop without unloading the application software from memory.

“Close” differs from “exit” in that the elements might still be resident in memory but are no longer visible or directly accessible from the screen.

See also exit.

.cmd file In running text, use a period preceding the file name extension (.cmd) and mark it up with the Filename element, or use the abbreviation “CMD file.”

cmdlet Noun. Pronounced “command-let”.

A lightweight Windows PowerShell script that performs a single function.

CMOS Always use the acronym instead of the expansion “complementary metal oxide semiconductor.”

CN Capitalize the abbreviation, but lowercase the expansion (common name). However, if it is a selectable property (the Common Name property) or attribute, the name has initial caps.

coaxial connection Use “coaxial cable connection” on first reference.

cold start Do not use. This term is difficult to translate into other languages. Instead, tell the user the exact procedure to follow; that is, which keys to press.

collapse / expand To use the mouse or control keys to show or hide the items in a directory structure.



combination box

combo box

Do not use in user documentation. Use “text box” to refer to the text box portion of a combination box, and “list box” to refer to the list portion.

Example: Type the name of the file in the File text box or select the name from the list box underneath.

If possible, use just the name of the option or dialog box area instead of calling it a “box” or “field.”

command In the Windows environment, do not use for a menu item or choice.

command button A control in a window or dialog box that initiates or cancels an action. Each button is labeled with the action it initiates. In most cases, you can just use the label text to refer to a button (“Click OK” instead of “Click the OK button”). See “Graphical User Interfaces” on page 152 for more information.

command line Not hyphenated, either as adjective or noun.

The screen location where you type commands. For usage guidelines, see Section 3.7, “Command Line Terminology,” on page 123.

Compare with command prompt, console, shell, terminal, terminal emulator, and virtual terminal.

command prompt The short, configurable string that is printed at the start of each command line. For usage guidelines, see Section 3.7, “Command Line Terminology,” on page 123.

Compare with command line, console, shell, terminal, terminal emulator, and virtual terminal.

command qualifier Use “startup option” instead.

commentcomment outuncomment

Avoid using “comment out.” Use “comment” or reword the sentence. The opposite of “comment” is “uncomment” or “remove the comment.”

communication buffer Do not use “routing buffer.”

complementary metal oxide semiconductor

Always use the acronym “CMOS.”

compliance Use “compliance” to refer to people. Use “conformance” to refer to objects or things.

compose Refers to the parts that make up a whole. For example, “the keyboard is composed of keys and switches.”

Avoid using this word, because its shades of meaning are often misunderstood even by native English speakers. Use “include,” “contain,” “is made up of” or “forms” instead.

Example: The keyboard includes keys and switches.Example: Several products form the core of the management platform

See also comprise.



comprise The whole “comprises” or “is composed of” its parts; it is never “comprised of” parts. For example, “the keyboard comprises keys and switches.”

Avoid using this word, because its shades of meaning are often misunderstood even by native English speakers. Use “include,” “contain,” “is made up of” or “forms” instead.

Example: The keyboard is made up of keys and switches.Example: The management platform contains several products.

See also compose.

compromise Avoid using. There are many meanings for this term in English, which makes translation difficult.

computer For generic references, use “computer” instead of “machine” or “system.” Use “device,” tablet device,” or “mobile device” for mobile devices. For increased clarity, use the terms “workstation,” “server,” or “mainframe” whenever possible.

Do not use multiple adjectives with this term. For example, you might need to say “desktop computer” or “personal computer,” but do not use the phrase “desktop personal computer.”

configuration control Use “change control” instead.

Configuration Control Board

Use “Change Control Board” instead.

conformance Use “compliance” to refer to people. Use “conformance” to refer to objects or things.

confirmation box A pop-up box that appears when the user is finalizing changes made in a utility or when exiting the utility. The user can answer a Yes/No confirmation prompt to confirm or reject changes.

considerations Used to describe information that should be kept in mind when making a decision. Generally, a consideration identifies key decisions, then briefly discusses the available options by suggesting examples for when to use each option or by listing the pros and cons for each option.

Compare with caveat, prerequisites, requirements, and guidelines.

console This term has several different meanings, depending on the product and the context. For definitions and for usage guidelines, see Section 3.7, “Command Line Terminology,” on page 123.

Compare with command line, command prompt, shell, terminal, terminal emulator, and virtual terminal.

contained The adjective “contained” is often redundant (as in the phrase “the features contained in this product?”). Use “the features in this product…” instead.

container For container objects, use “container object” in its first occurrence in the section, and as simply “container” on subsequent mentions.

continuous-form paper Note hyphen.

copy protect Verb: two words.



copy-protectedcopy protected

Compound adjectives should be hyphenated when they come before the word they describe. However, when they come after the word they describe, they do not use a hyphen.


GENOS is a copy-protected diskette.This diskette is copy protected.

core dump Noun: two words. Do not use as a verb.

core team In general, this term should be presented lowercase; however, it should be capitalized when it refers to a specific team.

counterclockwise One word.

covert entry Do not use.

CPIC Common Programming Interface for Communications. In some places, it appears as “CPI-C.” Do not use the hyphen.

cps Cycles per second. Use “Hz” (hertz) instead.

CPU Always use the abbreviation. Do not use the spelled-out term.

crash Avoid using this term unless documenting the UNIX crash command.

cross-domain Hyphenated when used as an adjective.

cross-reference Hyphenated in both the noun and verb forms.

CRT Use “monitor” instead.

CSDC Circuit-switched digital capability. Hyphenate “circuit-switched” in the extended form.

.csv file In running text, use a period preceding the file name extension (.csv) and mark it up as a file name, or use “CSV file.”

CSV Comma-separated values. Use uppercase when it is an abbreviation.

currently, presently In U.S. English, these are interchangeable, meaning “at the present time.” In British English, “presently” means “soon.”

cursor The blinking underline that marks the active editing point in text and moves as you enter text.

custom backup Use lowercase when you are referring to the type of backup. Use initial capitals on the term when you are referring to the option on the SBACKUP menu.

customer care Use initial capitals when you refer to the department. Use lowercase when you refer to the service in general.

D

database One word. Usually lowercase, unless it is part of a proper noun. (Oracle Database 12c, eDirectory database, ZENworks database)

data center Two words.

data circuit-terminating equipment

A variant of “data communications equipment.” Note wording and hyphen.



data file

Data file

Two words.

Use initial capitals on Data when you are referring to one of the types of files produced in a backup session (Data file, Error file, Log file).

data link

data-link

Noun: two words.

Adjective: Hyphenated.

data reliability

Data Reliability

Use lowercase when you refer to it as a generic term.

Use initial capitals when you describe an option in the System Fault Tolerance utility.

data terminal equipment

Use lowercase (do not present as Data Terminal equipment).

data-link switching Abbreviate as DLS. Do not use “DLSw” as an acronym for this term.

daylight saving time Lowercase. Remember that It is “saving” instead of “savings.”

dBASE Proper noun. Use capitalization as shown.

DC Not interchangeable with “VDC” (volts of direct current).

DDoS Abbreviation for Distributed Denial of Service. Pronounced “D-D-O-S”.

A cybersecurity event in which an attacker launches a DoS attack from many different computers distributed geographically and across multiple networks, such as by running bots on thousands of compromised systems without the owners’ knowledge.

See also DoS.

deallocate One word. Use a simpler term such as “release” or “free up” when writing for nonprogrammers.

decode Verb. Do not use as a noun.

decrement Noun or adjective.

Sometimes used as a verb, although Webster’s has not yet accepted it as such. Use as a verb only in content for a technical audience to refer specifically to decreasing an integer count by one.

de-emphasize Hyphenated.

default Use as either an adjective or a verb. Do not use to mean “Cancel” or “Undo.”

default server Do not confuse this with “preferred server.” They are not interchangeable.

deletable Note spelling.

delete To remove or discard something (such as a file or directory) that no longer has apparent value or usefulness. In computer usage, deleted items are often held in a storage area (such as a trash bin) for potential recovery. If the storage area is purged (as when the trash bin is emptied) the deleted item can no longer be recovered.

Delete Use this form for the Delete key.



deprovision

deprovisioning

Verb: one word. To disable a user account for a service.

Noun or adjective: one word.

Merriam-Webster does not acknowledge deprovision or de-provision as words. If you hyphenate the terms as de-provision and de-provisioning, use them consistently within your doc set.

deselect / select To use the mouse or control keys to mark or unmark an item.

desktop In the Windows interface, the screen background where windows, icons, and dialog boxes appear.

desktop personal computer

The word “desktop” in this phrase is unnecessary. Use “personal computer” instead.

device Use as a reference for mobile devices such as smartphones, pagers, iPads, and so forth. “Tablet device” and “mobile device” are variations you can use if you need to distinguish among different types of mobile devices.

device name Two words.

DHCP Abbreviation for Dynamic Host Configuration Protocol. Capitalize as shown.

DHCP relay agent “BOOTP relay agent” is the preferred term. Do not use “DHCP forwarder” or “BOOTP forwarder.”

dial automatically Two words. Do not use “auto-dial” as either a noun or a verb.

dial-in Use only as an adjective.

For the verb, use “dial.”

dial in-dial out Often used in lowercase: “dido.”

dial-up Hyphenated. Use only as an adjective.

For the verb, use “dial.”

dialog When you are documenting a Linux interface, use this term as appropriate, such as in the YaST installation workflow, where the sequential dialogs are full screen, without frame.

dialog box In the Windows interface, a secondary window that has a title bar, a title, and the close button in the upper right corner. It can have a “What’s This” button, but does not have scroll bars and is not usually sizeable. A dialog box usually opens from another window to provide a place for users to make a selection or to provide additional information.

When you are documenting the Windows interface, do not abbreviate the term to “dialog.”

When you refer to options in a dialog box, use the phrase “In the dialog box” instead of “on the dialog box.”

In Multiprotocol Router documentation, this term is avoided in favor of the generic entity “screen.”

See also window, pane, property page, page, and screen.

DIDO Dial in-dial out. Often used in lowercase: “dido”.



different This adjective is often unnecessary, as in the phrase “in 14 different examples.” Use phrases such as “in 14 examples” instead.

dimmed An option, menu item, or other interface element that is displayed in gray to indicate that it is cannot be selected.

Do not use “grayed” or “grayed-out”as a synonym. Use “unavailable” instead.

directory / folder For Linux and UNIX, use “directory.”

Example: Export the directory holding the installation data to the network.Example: Create a directory for the ISO image.

For Windows, use “folder” when you refer to the visual representation or object in the interface. Use “directory” for references to the structure of the file system.

Example: You can find the file in the Color folder.Example: Use the Administrative Tools folder for programs for IT professionals. Example: The system files are in the System subdirectory in the Windows directory.Example: The topmost directory in the hierarchy is called the root directory.

directory tree In eDirectory documentation, use “eDirectory tree” instead of “directory tree.”

dirty cache block When you use “dirty cache block” instead of “dirty cache buffer,” the emphasis is on a unit of measure on the disk that is used in swapping with cache memory or in holding material that will be written to disk.

dirty cache buffer Do not use “dirty cache block” as a synonym for this term. When you use dirty cache buffer instead of dirty cache block, the emphasis is on the function of the memory as a temporary holding place and as a way of providing quicker access to frequently requested data.

disable To turn off or temporarily prevent an event, function, or feature.

disabled Use “available” and “unavailable” in reference to commands or options that are in a usable or unusable state. Use “dimmed” to describe the appearance of an unavailable command or option.

The term is presented in lowercase when it refers to a state of being (generic reference to a specific state), but is capitalized (Disabled) when describing a status value.

disc Refers to a video, audio, or optical disc only, not a computer disk or diskette.

discover automatically Verb: two words. Do not use “autodiscover” or “auto-discover.”

disk Usually refers to a computer hard disk. Also used in some commonly understood expressions such as “boot disk” or “floppy disk.”

disk subsystem Use both words, not just “subsystem.”

diskette Do not use to refer to a hard disk (not even the removable kinds).

displays / appears The verb “display” is transitive, which means that it needs a direct object. “Appears” does not need a direct object.

Wrong: The message displays.Right: The message appears.Right: The message is displayed.

display filter Do not use “postfilter.”



distance vector Use this term only after first using the full term (distance vector algorithm). Note that this term is presented without hyphenation as either a noun or an adjective.

distance vector algorithm

After the first occurrence of this term in any discussion, the word “algorithm” can be dropped.

ditto Do not use this term in user interface design. It is too general.

DLSw Do not use for “data-link switching;” use DLS instead.

DN Capitalize the abbreviation, but lowercase the expansion (distinguished name). However, if it is a selectable property (the Distinguished Name property) or attribute, the name has initial caps.

DNS name server The acronym DNS can mean domain name server, domain name service, or domain name system, depending on context and the technology being discussed. “DNS server” could be correct usage if it is used to mean “domain name system server” or “domain name service server;” however, “DNS name server” is always incorrect because it is redundant in any context. Writers should ensure that their usage of the acronym is correct and consistent throughout a given documentation set.

DoS Abbreviation for Denial of Service. Pronounced “D-O-S”.

A cybersecurity event in which an attacker attempts to prevent authorized users from accessing information or services by flooding the targeted computers and network with information or requests for service.

See also DDoS.

double-click Hyphenated. To click a mouse button twice in quick succession.

Do not use with “on,” as in “click on.” (Double-click a VM in an In Progress state to display its Event Log option.

down Do not use; use “bring down” (as in “Bring down the server”).

download To transfer files from one computer or network system to another, usually by using a network or modem connection.

See also upload.

drag To move an item on the desktop by selecting the item, then pressing and holding the mouse button while moving the mouse.

To perform an action with a contact gesture on a touch screen or mobile device to move an item, text, or other content to where you want it.

Do not use 'click and drag' or 'drag and drop.' The action of dragging includes selecting the item and dropping it in place.

Wrong: Click and drag the folder to drive D.Right: Drag the folder to drive D.

Wrong: Drag and drop the appropriate icon onto the Applications panel. Right: Drag the appropriate icon from the palette to the Applications panel.

drag-and-drop Use only as an adjective, not as a noun or as a verb.

Example: Moving files is an easy drag-and-drop operation.



drop To place a dragged item by releasing the mouse button.

To place a dragged item by ending a contact gesture on a touch screen or mobile device.

drop-down Hyphenated when used as an adjective.

drop-down list A standard Windows control that displays a current setting, but can be opened to display a list of additional choices. An editable drop-down list is a combination of a drop-down list and an editable text box.

Refer to the option as “list” or “menu.” It is preferable to refer to it only by the field label.

Wrong: Click the Owner drop-down menu, then type or select a user name.Right: Click Owner, then type or select a user name.

drop-down menu The menu of alternative values that displays when a drop-down list box is expanded. Refer to the menu by its box label, such as the “Owner menu” instead of the ““Owner drop-down menu.”

due to / because of Use “because of.”

Wrong: The feature unlocks all passwords that were locked due to an intruder alert.Right: Because of the need to provide different configurations, new policies have

been added.

DVD Capitalize as shown.

E

email One word, no hyphen.

enable / enabled To turn on or to make available a function or feature.

Use “available” and “unavailable” in reference to commands or options that are in a usable or unusable state. Use “dimmed” to describe the appearance of an unavailable command or option.

end node Two words.

end point Two words.

end user

end-user

Noun: two words.


Avoid using this term. Use “you” or “user” instead. Use only in the rare case where you might find it necessary to contrast more than one category of user.

end result Use “result” instead.

ensure To make sure, certain, or safe. Do not confuse with assure and insure.



ensure / ensure that Use “that” when “ensure” introduces a phrase.

Example: Ensure that the volume is mounted.

Use “ensure” instead of “make sure.” Follow it with “that” except when it is followed by a noun.

Example: For best performance, ensure that you install only on recommended hardware.

Example: To ensure readability, use camel-case capitalization in variable names.

enter To type text or commands and then press Enter.

Contrast with type and specify.

For a discussion of using “type” and “enter,” see Section B.5, “Type or Enter,” on page 266.

enter into Use “enter” instead.

Ethernet Proper noun. Capitalize as shown.

eventually Avoid using this word. Although its English meaning is “occurring at an unspecified time in the future,“ its French equivalent means “possibly,” “perhaps,” or “should the occasion arise.” Instead, use “in the end” or “ultimately.”

exit To terminate an application. Exiting closes all windows opened by the application and shuts down the application. Some applications invoke the exit function with the Quit command.

Do not use “exit from” (the “from” is redundant).

See also close.

exit from the program Use “exit the program” instead.

expand / collapse To use the mouse or control keys to show or hide the items in a directory structure.

Ext3Ext4

Proper noun. Capitalize as shown. Use this capitalization for all versions of the Ext file system standard.

F

facilitate Use “enable” instead.

FDN Capitalize the acronym, but lowercase the expansion (fully distinguished name). However, if it is a selectable property (the Fully Distinguished Name property) or attribute, the name has initial caps.

features contained in this product

Use “features in” instead.

fiber-optic cable Hyphenate as shown.

field Where possible, use the name of the dialog box option instead of using the word “field.” If you need to distinguish between two options or refer to a group of options, use “field” instead of “box” where possible.

Example: Press Enter to move the cursor to the unlabeled fields beneath your name.Example: Fill in the following fields:

file name Two words.



file server Two words.

file system Two words.

firewall One word.

folder / directory For Linux and UNIX, use “directory.”

Example: Export the directory holding the installation data to the network.Example: Create a directory for the ISO image.

For Windows, use “folder” when you refer to the visual representation or object in the interface. Use “directory” for references to the structure of the file system.

Example: You can find the file in the Color folder.Example: Use the Administrative Tools folder for programs for IT professionals. Example: The system files are in the System subdirectory in the Windows directory.Example: The topmost directory in the hierarchy is called the root directory.

for, since, as Use “because” to express a cause or reason. Avoid using “since,” “for,” and “as” when “because” will convey your meaning effectively.




format To initialize a diskette or hard disk to enable it to recognize and store data.

forward slash Two words.

four out of five Use “four of five” instead.

front-end Noun or adjective: one word, hyphenated.

FTP Abbreviation for File Transfer Protocol. Capitalize as shown.

G

Get / GET Lowercase when used as an FTP command; uppercase when used as an SNMP operation.

GIMP Proper noun. Acronym for GNU Image Manipulation Program.

gotcha Do not use this term in product documentation.

Compare with caveat, prerequisites, requirements, guidelines, and considerations.

Go To Two words with initial capitalization. Do not use “Go To Page” or “GOTO.”

graphics Use as the adjective form rather than “graphical.” The only exception to this is “graphical user interface.”

grayed Do not use as a synonym for disabled, unavailable, or dimmed.

greater When you instruct users to use the last in a series of versions, patch updates, or service packs, use the word “later” or “latest” instead of “higher,” “greater,” above, or “newer.”



group box An area in a dialog box where similar options are grouped together. A group box has a frame or line around it, and a title within the frame. In most cases, you can use just the title if you need to refer to the area, instead of referring to it as a box.

Preferred: Select a Mail and Phone option.Alternative if necessary for clarity: In the Mail and Phone group box, select an option.

GRUB Acronym for Grand Unified Bootloader. Capitalize as shown.

GUI Acronym for graphical user interface. Capitalize as shown.

guidelines Used to describe information that directs a course of action, identifies pitfalls, or specifies practical techniques, best practices, or recommendations to achieve a desired outcome and avoid making errors.

Compare with caveat, prerequisites, requirements, and considerations.

H

hard disk Two words.

hard copy

hard-copy

Noun: two words.

Adjective: one word, hyphenated.

hard link Noun: two words.

For the verb, use “create a hard link.” Do not use “hard link” as a verb.

have to Use “need to” or “must” instead.

Wrong: You don't have to install it separately.Wrong: You have to set up a schema.Wrong: Server components have to be configured.Right: You must delete and re-create the secret.Right: You need to turn off the JIT compiler.

Help / help Recommended for user interface design as a standard menu heading. Also recommended as a feature name. Help is presented with initial capitalization in both usages.

Example: Select How Do I to see task-related Help topics.

When you are not referring to the interface item or the feature name, use lowercase.

Example: Check the most recent help files into the appropriate build directory.

When help is used as an option for a command, present the option in lowercase, without initial capitalization. Do not translate it.

help desk Two words.

higher When you instruct users to use the last in a series of versions, patch updates, or service packs, use the word “later” or “latest” instead of “higher,” “greater,” above, or “newer.”

highlight Use “select” instead.

See also click.

host name Two words.



hover Do not use this term to mean the action of pausing above something on-screen, usually to display a tooltip or balloon help. Use “point to”, “pause on”, or similar phrase instead. The goal is to dissociate the action from the hardware interface used to control the cursor movement: mouse, touchpad, touchscreen, or joystick.

.html file In running text, use a period preceding the file name extension (.html) and mark it up as a file name, or use “HTML file.”

HTML Hypertext Markup Language. Use uppercase when it is an abbreviation.

httphttps

In a URL, use lowercase.

HTTP

HTTPS

Hypertext Transfer Protocol. Use uppercase when it is an abbreviation.

Secure Hypertext Transfer Protocol. Use uppercase when it is an abbreviation.

I

if / then Do not use this pair of words as correlative conjunctions if the sentence is not grammatically parallel. In most cases, you do not need “then.”

Chicago says “Correlative conjunctions must frame structurally identical or matching sentence parts; in other words, each member of the pair should immediately precede the same part of speech.”

Example: If the first claim is true, then the second claim must be false.

If the structure is not parallel, do not use “then.”

Original: If the element does not contain any data, then it is represented as \0\0.Revised: If the element does not contain any data, it is represented as \0\0.

if / when Use “if” for a conditional event, and use “when” for an inevitable event, or to denote passage of time.

Example: If the prompt is displayed…Example: When the prompt is displayed…Example: When setup is complete…

if / whether Use “if” to express a condition and use “whether” for an alternative or possibility. Do not use “whether or not” as a synonym for “whether.”

Example: If you do not want to use the default, select another option.Example: To find out whether the fonts are available…Example: Decide whether to choose the first option or the second option.

image map Two words.

inactive window Any open window the user is not currently working in.

.ini file In running text, use a period preceding the file name extension (.ini) and mark it up as a file name, or use “INI file.”

initial Use “first” instead.



in front of / next to Use “next to” when you want to direct users to a check box for a particular list item or option, especially if the check box is selectable and the text for the item is not. “Next to” is more accurate, especially for users whose native language does not read right-to-left.

However, this usage should not be your first choice when you tell users to select an option that has a check box. The preferred usage is to give the option name without reference to the check box, such as "Select Mail to search for an email message." If you need to direct attention to the check box, you can use "Select the Mail check box to search for an email message.”

insecure Do not use this form to describe the relative security of systems, software, or processes. When possible, use “not secure.” Use “non-secure” (hyphenated) when you need an adjective to directly describe a word.

Preferred usage: This kind of password is not secure.When you need an adjective: The default non-secure port is 8008, and the default

secure port is 8009.

insert Do not use to mean simply “add.”

inset A box that displays information that cannot be edited (such as the name of a directory owner).

install To set up and configure software, hardware, or both for operation.

installation programinstall programinstall

Use “installation program.”

insure To provide or obtain insurance. Refers only to financially protecting something against loss. Do not confuse with assure or ensure.

Internet Proper noun. Use initial capitalization.

See also intranet.

interoperabilityinteroperateinteroperable

One word, no hyphen.

intranet Lowercase.

See also Internet.

IPsec Internet Protocol Security. An IETF standard. Capitalize as shown.

irregardless Use “regardless” instead.

it is this command that Use “this command” instead.

J

.jpg file / .jpeg file In running text, use a period preceding the file name extension (.jpg or .jpeg) and mark it up as a file name, or use “JPG file” or “JPEG file.”

JPEG Joint Photographic Experts Group. Use uppercase for the acronym.

K

keep-alive packet Hyphenate as shown.



keyboard shortcut A combination of keystrokes used to perform a task that is usually performed by using the mouse.

Use “keyboard shortcut” instead of “shortcut key.”

kind of Avoid using this common but vague phrase. For example, in the phrase “the kinds of features that are…”, the words “kinds of” can be omitted with no loss of meaning.

L

later, latest When you instruct users to use the last in a series of versions, patch updates, or service packs, use the word “later” or “latest” instead of “higher,” “greater,” above, or “newer.”

Example: You must use Windows Server 2012 R2 or later.Example: You need an Intel Core i5 processor or later.Example: Each machine must have OES 2015 with the latest service pack applied.

length This word is often redundant when used as an adjective. For example, in the phrases “2 feet in length” and “for a length of time” the words “in length” and “length of” are unnecessary.

lets / allows /enables In some older documentation, “lets” was the preferred usage. The distinction is no longer used, but you should be consistent within a documentation set.

Use “allows” when you mean permission.

Use “enables” when you mean capability.

letter-quality Hyphenated when it is used as an adjective.

.lex file In running text, use a period preceding the file name extension (.lex) and mark it up as a file name, or use “LEX file.”

lifecycle One word.

list box A box within a window or dialog box that lists all available choices, such as a list of all the files within a directory. If all choices aren’t visible, it includes a scroll bar.

Use instead of “select box”, “drop-down box”, “drop-down list”, “drop-down”, or “pull-down”.

See also drop-down list.

load automatically Verb: two words.

For the noun or adjective, use “autoload.” Do not use “auto-load.”

localized versionnon-English version

Use “non-English version.”

locate This term can mean either “find” or “place precisely in position.”

login

log in

Noun or adjective: one word. Do not use “log-in.”

Verb: two words.

Do not use “logon” and “log on.”

To establish a connection to a computer system, network, or online information service by entering a command and password.



logout

log out

Noun or adjective: one word. Do not use “log-out.”

Verb: two words.

To relinquish a session and sign off a computer system or online information service by entering a command and password.

long name space Three words, lowercase.

long-term graph Use hyphenation as shown.

lookup

look up

Noun or adjective: one word. Do not use “look-up.”

Verb: two words.

M

machine For generic references, use “computer” instead of “machine” or “system.” Use “device,” tablet device,” or “mobile device” for mobile devices. For increased clarity, use the terms “workstation,” “server,” or “mainframe” whenever possible.

make suremake sure that

Use “ensure” or “ensure that” instead.

manifest Avoid using this term. It can mean either “show” or “have.”

map To assign a drive letter to a particular directory path on a volume.

master replica Lowercase.

may Avoid using. Instead, use “can” to express ability, “might” or “could” to show a possibility, and “perhaps” to express a subjunctive mood.


meta tag Two words.

An identifying tag for HTML or XML documents. Meta tags allow information such as keywords that identify content, the author’s name, and other descriptive details.

metadata One word.

Data about data; for example, tags that indicate the subject of an HTML document.

metafile One word.

A file containing information that describes or specifies another file. Most often used in references to WMF, CGM, and EMF graphics formats.

MIB-I Note hyphen. Management Information Base I, defined in SNMPv1.

MIB-II Note hyphen. Management Information Base II, defined in SNMPv2.

might, may, can Use “can” to express ability, “might” or “could” to show a possibility, and “perhaps” to express a subjunctive mood.




mobile device Use “device” as a reference for mobile devices such as smartphones, pagers, iPads, and so forth. “Tablet device” and “mobile device” are variations you can use if you need to distinguish among different types of mobile devices.

modify In user interface design, use of “modify” is discouraged. Use “edit” instead, as in “Edit settings.”

.mor file In running text, use a period preceding the file name extension (.mor) and mark it up as a file name, or use “MOR file.”

mouse over Do not use this term to mean the action of pausing above something on-screen, usually to display a tooltip or balloon help. Use “point to”, “pause on”, or similar phrase instead. The goal is to dissociate the action from the hardware interface used to control the cursor movement: mouse, touchpad, touchscreen, or joystick.

multivalue One word, no hyphen. Do not add a terminal “d” (multivalued) in the phrase “multivalue parameter.”

N

name space Two words.

.ncf file In running text, use a period preceding the file name extension (.ncf) and mark it up as a file name, or use “NCF file.”

need to Use this term or use “must” instead of using “have to.”

Wrong: You don't have to install it separately.Wrong: You have to set up a schema.Wrong: Server components have to be configured.Right: You must delete and re-create the secret.Right: You need to turn off the JIT compiler.

network together Use “network” instead.

newer When you instruct users that they need to use the last in a series of versions, patch updates, or service packs, use the word “later” or “latest” instead of “higher,” “greater,” above, or “newer.”

next to / in front of Use “next to” when you need to direct users to a check box for a particular list item or option, especially if the check box is selectable and the text for the item is not. “Next to” is more accurate, especially for users whose native language does not read right-to-left.

However, this usage should not be your first choice when you tell users to select an option that has a check box. You usually use just the option name without reference to the check box, such as "Select Mail to search for an email message." If you need to direct attention to the check box, you can use "Select the Mail check box to search for an email message."

non-English versionlocalized version

Use “non-English version.”

non-secure When possible, use “not secure” to describe the relative security of systems, software, or processes. Use “non-secure” (hyphenated) when you need an adjective to directly describe a word. Do not use “insecure.”

Preferred usage: This kind of password is not secure.Use when you need an adjective: The default non-secure port is 8008, and the

default secure port is 8009.



non-seed Hyphenated.

normal Avoid using the term “regular” if “normal” conveys your meaning. (“Regular” implies or describes something that occurs according to a fixed or prescribed pattern.)

note that Usually redundant. Avoid using.

not secure When possible, use “not secure” to describe the relative security of systems, software, or processes. Use “non-secure” (hyphenated) when you need an adjective to directly describe a word. Do not use “insecure.”

Preferred usage: This kind of password is not secure.When you need an adjective: The default non-secure port is 8008, and the default


numerous Use “many” instead.

O

once Avoid using “once” to mean “when” or “after.” Use “once” only to mean “one time.”

Ambiguous: Once the INSTALL program finishes loading the files on the hard disk, it displays the message “Installation Complete.”

Precise: When the INSTALL program finishes loading the files on the hard disk, it displays the message “Installation Complete.”

Precise: After the INSTALL program finishes loading the files on the hard disk, it displays the message “Installation Complete.”

Precise: After the INSTALL program finishes loading the files on the hard disk, it displays the message “Installation Complete” only once.

on-screen Hyphenated when it is used as an adjective.

open data-link interface Hyphenate as shown.

open To activate a software application or a particular document, feature, or window within an application.

open source Two words, no hyphen. Lowercase and not hyphenated, for example “open source software,” or “the idea behind open source is that the code is available.”

open up Use “open” instead.

optimal Use “best” instead.

option button A standard Microsoft Office forms control that allows a user to select from a fixed set of mutually exclusive choices.

Refer to option buttons by their label names instead of calling them "buttons" or “option buttons.” If you must refer to buttons in Microsoft Office by the generic name, call them "option buttons”, not “buttons” or “radio buttons.”

Use "select" or "deselect" as the verb.

Wrong: Click the Current Page option button.Wrong: Select the Current Page button.Preferred: Select Current Page.

See also check box and radio button

out Avoid using this word in expressions of quantity (such as in “four out of five…”). In this example, the word “out” is unnecessary and can be omitted with no loss of meaning.



P

package Use initial capitalization when it is part of a specific name (such as the Container Package object). Use lowercase when it is used generically, such as “different policy packages let you customize how the application works.”

packet-switched network

Use hyphenation as shown.

page Use to refer to the specific title of a property page, or to the display in a wizard.

Example: Click Previous to return to the previous page and change your selections.

pane A separate area in a window.

See also window.

partition automatically Verb: two words.

For the noun or adjective, use “autopartition.” Do not use “auto-partition.”

passphrase One word, no hyphen.

path name Two words.

.pdf file In running text, use a period preceding the file name extension (.pdf) and mark it up as a file name, or use “PDF file.”

PDF Portable Document Format. All three words have initial capitalization when you expand the abbreviation PDF.

per-call basis Use hyphenation as shown.

ping To test the connectivity of a particular network node by transmitting a diagnostic packet that requires a response from that node.

plan ahead Use “plan” instead.

please Do not use the word please when you give instructions to the user.

plug-in

plug in

Noun or adjective: one word, hyphenated.

Verb: two words.

Use plugin (one word, no hyphen) if the product or target industry uses this spelling. Either way, use it consistently in your doc set.

p.m. Present time of day abbreviations in lowercase, with periods but without spaces between the letters.

Example: The meeting will be held at 7:00 p.m.

.png file In running text, use a period preceding the file name extension (.png) and mark it up as a file name, or use “PNG file.”

PNG Portable Network Graphics. Use uppercase for the acronym.

pointer The arrow-shaped cursor that moves when the mouse moves. It indicates the area that is affected when you press a mouse button.

policy Lowercase when following a policy name, such as “Search policy.”

poll To manage the transmission sequence of devices on a shared circuit by sending requests for transmission to each device in return.



pop-up

pop up


Verb: two words.

preplan Use “plan” instead.

prerequisites “Prerequisites” usually refers to tasks that should be performed before continuing with a process described in the documentation. You can use either Prerequisites or Requirements or both as headings in documentation.

If you create a list for either prerequisites or requirements, use the checklist format.

You can also use tables for prerequisites or requirements, if the information can be more clearly presented in that format.

Compare with requirements, guidelines, and considerations.

press To use a keyboard key or mouse button to initiate whatever function that key or button is assigned to.

print out Use “print” instead.

property page A dialog box that opens from a button or menu selection and allows users to change the properties of an application, an object, a policy, and so forth.

.prs file In running text, use a period preceding the file name extension (.prs) and mark it up as a file name, or use “PRS file.”

pull-down list Use list box instead.

pull-down menu If you are referring to a list of choices in a dialog box or window, use list box instead.

Q

Quick StartQuick Start card

Use “Quick Start.” The word “card” implies that it is printed, which is probably not the case.

quit Use “exit” instead.

quite Avoid using. Use “very” or “completely” instead.

R

radio button A control that allows a user to select from a fixed set of mutually exclusive choices. Radio buttons are used in software. Microsoft Office uses “option buttons” for forms you create.

Refer to radio buttons by their label names instead of calling them "buttons" or “radio buttons.” If you must refer to them by the generic name, call them "radio buttons” for dialog boxes in software. Call them “option buttons” for Microsoft Office forms.

Use "select" or "deselect" as the verb.

Wrong: Click the Current Page radio button.Wrong: Select the Current Page button.Preferred: Select Current Page.

See also check box and option button.

RDN Capitalize the acronym, but lowercase the expansion (relative distinguished name). However, if it is a selectable property (the Relative Distinguished Name property) or attribute, the name has initial capitals.



read/write replica Lowercase.

real time

real-time

Noun: two words.


reconfigure back Use “reconfigure” instead.

refer back Use “refer” instead.

regular / normal In U.S. English, “regular” and “normal” are often used interchangeably. But note that “regular” implies something that occurs according to a fixed or prescribed pattern; “normal” implies something that occurs in a natural way.

reboot / boot To start or restart a server or workstation in a Linux or UNIX environment.


See also start / restart.

re-create Hyphenated when it means “to create again.”

release notes Term replaces “readme.” Prepare release notes for each release: major (X.0), minor (X.#), service pack (X.X.#), hotfix (X.X.X.#), and patch update (PX). Engineers are responsible for the notes that accompany Field Test Files (FTFs) and cumulative patch updates comprised of FTFs.

remove To make something (such as a file or directory) inactive by taking it out of a place or position and putting it somewhere else.

restart / start To start or restart software, such as a gateway, utility, or agent.


See also reboot/boot.

remainder Use “rest” instead.

replace This term can mean either “put back the original where you found it” or “throw away the old and use a new one.”

requirements “Requirements” usually refers to items, such as software or hardware, that need to be in place before continuing. You can use either Prerequisites or Requirements or both as headings in documentation.

If you create a list for either prerequisites or requirements, use the checklist format.

You can also use tables for prerequisites or requirements, if the information can be more clearly presented in that format.

Compare with prerequisites, guidelines, and considerations.

re-sort Hyphenated when it means “to sort again.”

restore To reinstate files or data deleted in an immediately preceding action.

right-click Hyphenated.

rollover, roll over Do not use this term to mean the action of using the mouse pointer to point at something on-screen, usually to display a tooltip or balloon help. Use “mouse over” instead.



route To direct a message packet from one node (source) to another (destination).

runnable Two ns.

runtime One word, no hyphen.

S

salvage Do not use to mean to recover lost or previously deleted files or data. Use “restore” instead. If it appears in the UI, describe the action as restore.

Example: To restore the previously deleted files, click Salvage.

sAMAccountName Proper noun.

The LDAP display name of the SAM Account Name attribute in Active Directory.

screen Use as a reference to a command line utility or a character-based interface.

See also dialog box, window, pane, property page.

screen shotscreen capture

“Screen shot” is preferred. The term is used in some open source documentation and in documentation for a command line utility or character-based interface. However, you should use “illustration” or “graphic” in documentation for Windows-based applications.

scroll To move through the text display of a window or list box either by clicking the arrows at the ends of a scroll bar or by using keyboard arrows when the cursor is within the text.

scroll arrow The arrow-shaped area of the scroll bar that controls which direction you scroll.

scroll bar The bar that appears on the bottom or right edge of a window. It contains controls that support scrolling through window contents.

.sdb file In running text, use a period preceding the file name extension (.sdb) and mark it up as a file name, or use “SCB file.”

secure When possible, use “secure” and “not secure” to describe the relative security of systems, software, or processes. Use “non-secure” (hyphenated) when you need an adjective to directly describe a word. Do not use “insecure.”

Preferred usage: The password is not secure.When you need an adjective: The default non-secure port is 8008, and the default


select To highlight or single out a particular element or object, or group of elements or objects, with the implied intent to execute an action, process, or command exclusively upon that selection. Use this term to indicate items on a computer interface or mobile device screen.

Use instead of “choose,” “block,” or “highlight.”

Use “deselect” when you unmark something that was previously selected.

server name Two words.

service pack Use initial capitals when you refer to a specific service pack, and use lowercase when it is generic.

set To establish certain selectable parameters, formats, and preferences as defaults.



setup

set up

Noun or adjective: one word, no hyphen.

Verb: two words.

shell A software interface between the user and the computer's operating system. For usage guidelines, see Section 3.7, “Command Line Terminology,” on page 123.

Compare with command line, command prompt, console, terminal, terminal emulator, and virtual terminal.

sheet feeder Two words.

shortcut key Use “keyboard shortcut” instead.

shortcut menu For the menu that appears when you right-click, Microsoft uses “shortcut menu.” Use a phrase such as “Right-click to display a menu of options,” or “Right-click, then select Paste.”

since, for, as Use “because” to express a cause or reason. Avoid using “since,” “for,” and “as” when “because” will convey your meaning effectively.




SLED / SLES / SLE Never use SLE as an acronym for SUSE Linux Enterprise. Using SLES for SUSE Linux Enterprise Server or SLED for SUSE Linux Enterprise Desktop is acceptable on second reference only if repeated use of the full product name might create readability problems for the user.

snap-in

snap in


Verb: two words.

specify Use when there are multiple ways for a user to supply information, such as typing, copying and pasting, or selecting from a list.

Contrast with enter and type

Spell Check Use this phrase instead of “Speller” as the feature name.

spell-check Hyphenated when used generically as a noun, adjective, or verb. (Webster’s 11th)

SSH Do not use as a verb. Use “connect using SSH” instead.

stand-alone Hyphenated when used as an adjective or noun. (Webster’s 11th.)

start / restart To start or restart software, such as a gateway, utility, or agent.


See also boot/reboot.

startup disk Also called a “boot disk.” Use the term preferred in your technology, and be consistent within a given set of documentation.

status bar An area, usually at the bottom of an application window, that displays information about the content of the window.



status areastatus notification areanotification area

In Windows 2000 and later, the area of the taskbar that contains the clock, the volume control, and icons for programs that are running in the background. In earlier versions of Windows, it is called the system tray.

See also taskbar.

style sheet Two words, except in the expansion of the acronym XSL (Extensible Stylesheet Language).

sufficient Avoid using this word. When possible, use “enough” instead.

supervisor

Supervisor

SUPERVISOR

Use lowercase for generic usage, as in “network supervisor.”

Capitalize when you use it as an object or as a property right.

Use uppercase when it refers to the username “SUPERVISER.”

symbolic link Noun: two words.

Do not use as a verb. Use “create a symbolic link” instead.

system Use generically to refer to computer configurations instead of the computer itself. The system includes the physical or virtual computer hardware, storage devices, and peripheral devices. It can include system software.

Example: System Requirements

For general computer references, use “computer” instead of “machine” or “system.” For increased clarity, use the terms “workstation,” “server,” or “mainframe.”

For general mobile computing references, use “device” or “mobile device.” For increased clarity, use the terms “tablet device,” “smartphone,” “laptop,” or “netbook.”

system registry Lowercase.

system tray In Windows 95, 98, and NT, the area of the taskbar that contains the clock, the volume control, and icons for programs that are running in the background. In Windows 2000 and later, it is called the status area, status notification area, or notification area.

See also taskbar and status area.

T

tab In a dialog box, a “tab” is the tabbed title that you click; it is not the property page or dialog box that opens. For more information and for specific usage examples, see “Graphical User Interfaces” on page 152.

tablet device Use “device” as a reference for mobile devices such as smartphones, pagers, iPads, and so forth. “Tablet device” and “mobile device” are variations you can use if you need to distinguish among different types of mobile devices.

taskbar The area usually located at the bottom of the Windows desktop. It includes the Start button, a button for each open primary window, and a status notification area. It can also contain the Quick Launch toolbar, which is the customizable area that contains icons you click to open a web browser, applications, and so forth.

See also status notification area.

telnet Do not use as a verb.



terminal A device or program that enables you to communicate with a computer. For more information and for usage guidelines, see Section 3.7, “Command Line Terminology,” on page 123.

Compare with command line, command prompt, console, shell, terminal, terminal emulator, and virtual terminal.

terminal emulator A GUI-based program that displays a window with a command line. For more information and for usage guidelines, see Section 3.7, “Command Line Terminology,” on page 123.

Compare with command line, command prompt, console, shell, terminal, and virtual terminal.

the kinds of features Use “the features that are” instead.

there is Avoid using this common phrase. For example, in the phrase “there is one key that allows” the words “there is” can be omitted with no loss of meaning.

the various components

Use “the components” instead.

.tif file In running text, use a period preceding the file name extension (.tif) and mark it up as a file name, or use “TIF file.”

TIF Tagged Image File. Use uppercase when it is an acronym.

time of day Use “time” instead.

time stamp Two words.

title bar The area at the top of a window that contains the window title and some of the window controls.

toolbar One word, no hyphen. Use to refer to customizable menu bars.

try to Avoid. Just use the preferred verb, such as “specify the settings accurately” instead of “try to specify the settings accurately.”

twisted-pair Hyphenated when it is used as an adjective.

type To display characters on the screen by pressing the corresponding keys on the keyboard.

Contrast with enter and specify.

For a discussion of using “type” versus “enter,” see Section B.5, “Type or Enter,” on page 266.

type in Use “type” instead.

U

unavailable Use “available” and “unavailable” in reference to commands or options that are in a usable or unusable state. Use “dimmed” to describe the appearance of an unavailable command or option.

uncheck Do not use. Use “deselect” instead when you refer to the action of removing a check mark from a check box.

uncommentcommentcomment out

Avoid using “comment out.” Use “comment” or reword the sentence. The opposite of “comment” is “uncomment” or “remove the comment.”



undelete Do not use to mean to reinstate files or data deleted in an immediately preceding action. Use “restore” instead. If it appears in the UI, describe the action as restore.

Example: To restore the database, click Undelete.

Unicode Note initial capitalization.

uninstall To delete a program or application from a system, along with its associated registry entries, files, and directories. This is usually done by running an uninstall program.

up Avoid using this term as a synonym for “functioning” or “operating.”

This term is presented in lowercase when it refers to a state of being, and with initial capitals when it describes a status value. Do not present in all capitals.

upload To transfer files from a workstation or small network system to a larger computer system or network using a network or modem connection.

See also download.

uplink One word, no hyphen.

1. (verb) To transmit information by way of a land-based transmitter to a communications satellite.

2. (noun) A communications channel for transmission to a satellite.

user ID Two words. (It can be one word within syntax or code examples.)

user name Two words. (It can be one word within syntax or code examples.)

user-requested Hyphenated when it is used as an adjective.

utilize Use “use” instead.

upon Use “on” instead.

utilization Use “usage” instead.

V

various Avoid using this word. For example, in the phrase “the various components of” the word “various” can be omitted without any loss of meaning.

version Do not use “version” or “v” as part of the product name.

Wrong: PlateSpin Migrate Version 12.2.Wrong: PlateSpin Migrate v12.2.Right: PlateSpin Migrate 12.2.

version xxx release Use “version xxx” instead.

virtual terminal One of seven full-screen terminal displays on Linux. For more information and for usage guidelines, see Section 3.7, “Command Line Terminology,” on page 123.

Compare with command line, command prompt, console, shell, and terminal.

vCloud Proper noun. Capitalize as shown. Use VMware vCloud Director on the first occurrence in a section.

VMware Proper noun. Capitalize as shown.

volume name Two words



vSphere Proper noun. Capitalize as shown. Use “VMware vSphere” on the first occurrence in a section.

W

web Do not capitalize the word “web”, except when it is part of a proper noun such as World Wide Web, and according to normal capitalization rules.

Example: the webExample: web browserExample: web page

webcam One word, no hyphen. Apply normal capitalization rules.

webcast One word, no hyphen. Apply normal capitalization rules.

webmaster One word, no hyphen. Apply normal capitalization rules.

web page Two words. Apply normal capitalization rules.

web server Two words. Apply normal capitalization rules.

website One word, no hyphen. Apply normal capitalization rules.

when “When” refers to the time something happens. It can also replace “if” or “although,” but such usage can confuse a non-native English speaker. To avoid confusion, do not use these words interchangeably.

Ambiguous: Documents do not print properly when your printer lacks adequate memory.

Precise: Documents do not print properly if your printer lacks adequate memory.

where “Where” refers to a physical location. Do not use it unless you are referring to a specific location. Do not use “where” in place of “in which.”

Ambiguous: For optimal performance, create an index where the join field of the secondary table is the first or only segment.

Precise: For optimal performance, create an index in which the join field of the secondary table is the first or only segment.

whether / if Use “if” to express a condition and use “whether” for an alternative or possibility. Do not use “whether or not” as a synonym for “whether.”

Example: If you do not want to use the default, select another option.Example: To find out whether the fonts are available…Example: Decide whether to choose the first option or the second option

whether or not Use “whether” instead.

while “While” means “for a period of time,” “as long as,” or “during the time that.” Use this term to indicate a time relationship. Avoid using it as a substitute for “and,” “but,” or “although.” Readers whose command of English is not strong find it difficult to understand the contexts in which this word is sometimes used. To indicate a contrast or a link, use “but,” “in contrast,” or “although.”

Ambiguous: The file server has 8 GB of memory while the workstation has only 2 GB.

Precise: The file server has 8 GB of memory; in contrast, the workstation has only 2 GB.

Precise: The program checks for viruses while the files are being copied.



3.3 Latin Terms and AbbreviationsDo not use any Latin terms or abbreviations. Use these English equivalents instead:

white paper Two words.

Wi-Fi Proper noun. Use when you refer to IEEE 802.11 protocols, networks, and access points. Use “wireless network” when you refer generically to any non-802.11 wireless communication technology, or specify the appropriate technology (LTE, WiMAX, microwave, infrared, Bluetooth).

window In the Windows interface and in an Internet browser, an area that has a title bar, a title, and the close, minimize, and maximize buttons in the upper right corner. It can have an icon representing the document or application that is running in it, a scroll bar if necessary, can be sizeable, and can be divided into different areas called panes.

See also dialog box, pane, property page, and screen.

Example: Use the Exploring window to navigate through directories and folders.Example: Select the directory in the left pane of the window.

wish Avoid using this term. Use “want” instead.

Wizard / wizard Use initial capitals if it is part of a utility name. Use lowercase if it is generic.

Example: The Migration Wizard steps you through the process.Example: The wizard asks if you want to migrate all servers.

World Wide Web Proper noun. Use initial capitals.

would like Avoid using this term. Use “want” instead.

.wpf file In running text, use a period preceding the file name extension (.wpf) and mark it up as a file name, or use “WPF file.”

.wpg file In running text, use a period preceding the file name extension (.wpg) and mark it up as a file name, or use “WPG file.”

write protect Two words.

write-protected Hyphenated when it is used as an adjective.

WYSIWYG Acronym for “what you see is what you get”. Do not spell out.

X

Xen Proper noun. Capitalize as shown.

XenServer Proper noun. Capitalize as shown. Use Citrix XenServer on the first occurrence in a section.

.xml file In running text, use a period preceding the file name extension (.xml) and mark it up as a file name, or use “XML file.”

XML Extensible Markup Language. Use uppercase for the acronym.


Latin English Equivalent

ad hoc improvised


3.4 Abbreviations for Units of MeasureFollow these guidelines for abbreviations of common units of measure. For style guidelines about using units of measure, see Section 1.1.6, “Abbreviating Units of Measure,” on page 21. For information about presenting dimensions, see “Dimensions” on page 45.

e.g. for example, such as, as in

et al. and the rest, and others

etc., et cetera including, and so forth

ibid already referenced, in the same place

i.e. that is

N.B. note

q.v. see

re concerning, about, in reference to

sic exactly produces

via by using, with, through

viz. namely

vs. against, compared to, compared with, versus

Latin English Equivalent

Term Abbreviation Example

bits per second bps 200 bps

decibel dB 40 dB

dots per inch dpi 300 dpi

exbibyte EiB 1 EiB

exabyte EB 1 EB

gigabit Gbit 8 Gbit

gibibyte GiB 3 GiB

gigabyte GB 3 GB

gigahertz GHz 2.4 GHz

hertz Hz 5 Hz

hexadecimal h (suffix)0x (prefix)

15h0x15

kilobit Kb 300 Kb

kilobits per second Kbps 50 Kbps

kibibyte KiB 200 KiB


3.5 Acronyms for Common Technical PhrasesFollow the capitalization and spelling guidelines for the acronyms for common technical phrases described in this section.

Spell out the phrase and parenthetically identify the acronym the first time the phrase appears in a topic. Use the acronym in all subsequent references. Exceptions to this rule are indicated. See Section 1.1, “Abbreviations and Acronyms,” on page 18 for additional style and usage guidelines.

Do not spell out well-known industry acronyms. See Section 1.1.7, “Using Well-Known Industry Acronyms,” on page 22.

For units of measure, see Section 3.4, “Abbreviations for Units of Measure,” on page 114.

kilobyte KB 200 KB

kilohertz kHz 100 kHz

megabit Mbit 100 Mb

megabits per second Mbps 50 Mbps (measurement for bandwidth and throughput on a network)

mebibyte MiB 40 MiB

megabyte MB 40 MB

megabytes per second MBps 119 MBps (measurement for data transfer speeds for read and write on a computer storage device)

megahertz MHz 10 MHz

millisecond ms 300 ms

pebibyte PiB 2 PiB

petabyte PB 2 PB

pixels per inch ppi 300 ppi

second s 30s

tebibyte TiB 10 TiB

terabyte TB 10 TB

volts V 8V

Term Abbreviation Example

Example: Specify the appropriate globally unique identifier (GUID).

A B C D E F G H I J

K L M N O P Q R S T

U V W X Y Z


3.5.1 A

3.5.2 B

3.5.3 C

Acronym Term, Compound Term, or Phrase

ADO ActiveX Data Objects

ALM Application Lifecycle Management

AMPS advanced mobile phone service

APE Alternate Property Editor

API application programming interface

ASF Apache Software Foundation

ASP application service provider

Always spell out at first mention because it also stands for Active Server Page.


B2B Business-to-business

B2C Business-to-consumer

BLOLB binary large object


CBT computer-based training

CCW COM Callable Wrapper

CGA color/graphics adapter

CGI common gateway interface

CLOB Character Large Object

Do not spell out at first mention.

CLR Common Language Runtime

CLS Common Language Specification

CORBA Common Object Request Broker Architecture

CR change request

CRM Customer Relationship Management

CSS Cascading Style Sheet


3.5.4 D

3.5.5 E


DB database

DBA database administrator


DBMS database management system

DDE Dynamic Data Exchange

DDL data definition language

DLL dynamic-link library

DML Data Manipulation Language

DNS domain name system

DOM Document Object Model

DSN Data Source Name

DSO Dynamic Shared Object

DTD document type definition


EAI Enterprise Application Integration

ECO Enterprise Core Objects

EEMS Enhanced Expanded Memory Specification

EGA enhanced graphics adapter

EJB Enterprise JavaBean

EMI electromagnetic interference

EMS Expanded Memory Specification

EOF end-of-file

EOL end-of-line

EPS Encapsulated PostScript

ERP Enterprise Resource Planning

ESQL Extended Structured Query Language

Also Embedded Structured Query Language

ETM External Translation Manager


3.5.6 F

3.5.7 G

3.5.8 H

3.5.9 I


FAQ frequently asked questions

Do not use the phrase an FAQ. Instead, use the term FAQ.

FCC Federal Communications Commission

FIFO first in, first out

FTP File Transfer Protocol (server protocol)


GAC Global Assembly Cache

.gif or GIF graphics interchange format


GUID globally unique identifier


HDML Handheld Devices Markup Language

HP Hewlett-Packard


IBX InterBase Express

IDE integrated development environment

IDL Interactive Data Language

IE Internet Explorer

IIS Internet Information Services

IP Internet Protocol

ISAPI Internet Server Application Programming Interface

ISBN International Standard Book Number


3.5.10 J

3.5.11 KNone.

3.5.12 L

3.5.13 M

ISDN Integrated Services Digital Network

ISO International Organization for Standardization

ISP Internet Service Provider

ISV Independent Software Vendor



.jar or JAR Java Archive


JHTML Java Hypertext Markup Language

JRE Java Runtime Environment

JVM Java virtual machine

.jpeg or JPEG Joint Photographic Experts Group


JIT just-in-time compiler (Java-related term)


LAN local area network


MDA Model-Driven Architecture

MDI multiple-document interface

MIME Multipurpose Internet Mail Extensions

Also Multimedia Internet Message Extensions


3.5.14 NNone.

3.5.15 O

3.5.16 P

.mp3 or MP3 Moving Picture Experts Group Layer-3 Audio


MS-DOS Microsoft disk-operating system


MSIL Microsoft Intermediate Language



OCL Object Constraint Language

ODBC Open Database Connectivity

OEM original equipment manufacturer

OLE object linking and embedding


OMG Object Management Group

OOP object-oriented programming

ORB Object Request Broker


PDA personal digital assistant

.pdf or PDF Portable Document Format


PE portable executable

PIM personal information manager

POA Portable Object Adapter

PS PostScript

PTT push-to-talk


3.5.17 Q

3.5.18 R

3.5.19 S


QBE query by example


RAD Rapid Application Development

RCW Runtime Callable Wrappers

RDBMS relational database management system

re / RE regarding

Always spell out.

RFC Remote Function Call

NOTE: Also stands for Request For Comments.

RTL runtime library

RTTI Runtime Type Information


SCC API Microsoft Common Source Code Control API

SCM Source Control Management

NOTE: Also stands for software change management and software configuration management.

SDI single document interface

SDK software development kit

SIM Subscriber Identification Module

SMS Short Message System

SOAP Simple Object Access Protocol

SP Service Pack

Example: Microsoft Windows NT 4.0 SP 6.

SSL Secure Sockets Layer


3.5.20 T

3.5.21 U

3.5.22 V

3.5.23 W

3.5.24 X


TSR terminate-and-stay-resident


UDDI Universal Description Discovery and Integration

UDP User Datagram Protocol

UML Unified Modeling Language

URI Uniform Resource Identifier

URL Uniform Resource Locator


VCL Visual Component Library

VCS version control system

VSS Microsoft Visual SourceSafe


W3C World Wide Web Consortium

WSDL Web Services Description Language

WWW World Wide Web


XMI XML metadata interchange

XMS extended memory specification


3.5.25 YNone.

3.5.26 ZNone.

3.6 GUI TerminologyFor information regarding the definition of graphical user interface terms, see the following terms in Section 3.2, “Terminology Spelling and Usage,” on page 77:

tab check box option button radio button group box command button

3.7 Command Line TerminologyThe following table gives additional information about Linux command line terminology. Product documentation should follow this usage where possible.

Table 3-1 Command Line Terminology Definitions and Guidelines

Term Definition Remarks

command line It is a space on the screen where you type commands.

command prompt A short, configurable string that is printed at the start of each command line.

console This term has various meanings, including the following:

A display for system log messages

ZENworks consoles

A terminal

Only components that include “console” in the name should be documented as consoles. Do not use it in place of “terminal.”

shell A software interface between the user and the computer's operating system. Sometimes used to refer to the user interface.

Red Hat often uses “shell” to refer to the command environment / terminal / command prompt / command line.

Use “shell” to refer only to a program that receives user input, processes that input, and passes the resulting instructions to the Linux operating system.

Use it only when you document the BASH shell or another Linux shell. Do not use it in place of “terminal.”


3.8 Pronouns That Need a Clarifying NounAlways follow the pronouns “this,” “that,” “these,” and “those” with a clarifying noun because they can be ambiguous when used as pronouns.

You should also follow these pronouns with a clarifying noun:

terminal In the early days of computing, a terminal was a keyboard/monitor combination that enabled users to interact with a central computer. Today it is a program that provides the functionality of a traditional terminal. To Linux administrators, the instruction to “open a terminal” translates to “access a command line.”

terminal emulator A GUI-based program that displays a window with a command line.

Linux administrators understand “open a terminal.” Saying “run a terminal emulator” is verbose and unnecessary.

Do not use it unless the instructions can only be completed in a terminal emulator and not in a virtual terminal.

virtual terminal One of seven full-screen terminal displays on Linux that are accessed by pressing Ctrl+Alt+Fn, where n is the number of the terminal you want.

If a Linux GUI is loaded, it runs in virtual terminal 7. The other six terminals display either a login prompt for accessing the BASH shell, or text that has been generated by programs that are running on the system.

Linux administrators understand “open a terminal.” Saying “open a virtual terminal” is verbose and unnecessary.

Do not use it unless the instructions can only be completed in a virtual terminal and not in a terminal emulator.

Term Definition Remarks

Wrong: A procedure cursor is associated with an EXECUTIVE PROCEDURE statement. This allows you to scan multiple rows of data.

Right: A procedure cursor is associated with an EXECUTIVE PROCEDURE statement. This cursor allows you to scan multiple rows of data.

any few one some

another many other your

each neither own

either none several


3.9 Transitional Words and PhrasesUse simple, direct transitional words and phrases for readability and ease of translation.

Purpose Transitional words Recommended

Compare similar ideas In the same waylikewiseresemblingsimilarly

similarly

Contrast ideas after allcompared withconverselyin contrast toinsteadneverthelesson the contraryotherwisestillyet

instead

Link thoughts againbesidesfirstfurtherlastlikewisemoreovernext

firstlastnext

Show sequence and time afterwardat the same timeduringearlierfirst (and second, third, etc)followinglastlaternextsimultaneouslywhile

first (and second, third, etc)lastnextwhile

Show cause and effect accordinglybecauseconsequentlythenthereforethus

Because

Summarize in conclusionin summarythus

Rarely used in technical writing


3.10 Verbs of PersonificationUse the following tables for information about avoiding verbs that suggest personification.

Section 3.10.1, “Cognition,” on page 126 Section 3.10.2, “Communication,” on page 126 Section 3.10.3, “Sight or Perception,” on page 127 Section 3.10.4, “Want or Need,” on page 127

3.10.1 Cognition Avoid using verbs that attribute human cognitive capabilities to equipment. The following list

gives examples of such verbs to avoid:

Use inanimate verbs to designate the cognitive capabilities or actions of equipment. The following list gives examples to use in place of the human verbs listed in the previous rule:

3.10.2 Communication Avoid using verbs that attribute human communication capabilities to equipment. The following

list gives examples of such verbs to avoid:

Use inanimate verbs to designate the communication capabilities or actions of equipment. The following list gives examples to use in place of the human verbs listed in the previous rule:

believe judge remember

consider know see

decide notice think

deliberate observe understand

intend realize watch or watch for

accept evaluate retain

choose interpret select

compare manipulate store

determine negate survey

distinguish recognize validate

equate reject

Wrong (human): The OS remembers the password.

Right (inanimate): The OS recognizes the password.

ask say

request tell


3.10.3 Sight or Perception Avoid using verbs that attribute human sight or perceptual capabilities to equipment. The

following list gives examples of such verbs to avoid:

Use inanimate verbs to designate the perceptual capabilities or actions of equipment. The following list gives examples to use in place of the human verbs listed in the previous rule:

3.10.4 Want or Need Avoid using verbs that attribute human wants and needs to equipment. The following list gives

examples of such verbs to avoid:

acknowledge introduce route

announce point show

communicate print signal

confirm prompt report

display respond

indicate report

Wrong (human): SESSION tells you to enter a directory path.

Right (inanimate): SESSION prompts you to enter a directory path.

Avoid Replace with

check to see observe

look see

notice watch or watch for

distinguish recognize verify

examine search or search for view

locate seek

monitor survey

Wrong (human): The program watches for errors and records them in the error log.

Right (inanimate): The program monitors errors and records them in the error log.

desire favor want

expect prefer wish


Use inanimate verbs to express the needs of equipment. The following list gives examples to use in place of the human verbs listed in the previous rule:

3.11 Redundant and Wordy Phrases to AvoidIn an effort to improve documentation usability through clear, concise writing, we have identified a list of redundant and wordy phrases that occur in our documentation. The table in this section shows examples of actual usage in our doc, along with a suggested alternative to tighten the wording.

As you write new documentation or make major changes to sections of existing documentation, watch for these phrases and consider using the suggested alternative. Ensure that you look at each phrase and choose the wording best fits the context (in other words, don't do a wholesale search and replace). Also, to make the best use your time and to avoid localization costs, don't go into existing documentation and update it simply for the sake of rewriting these phrases.

lack require

must wait for

need

Wrong (human): The program wants 40 MB of memory

Right (inanimate): The program requires 40 MB of memory.

Phrase Alternative Example

a large number of many The utility can use a large number of commandsThe utility can use many commands.

a number of several, some, many

Logging can be useful for a number of reasons.Logging can be useful for many reasons.

a period of time time, or a specific time reference.

During this period of time, you can change your selections.During this time, you can change your selections.After ten minutes, the selection window closes.

a question to ask question I have a question to ask.I have a question

a small number of a few After you create a small number of policies...After you create a few policies...

adequate enough adequate The amount of memory is adequate enough.The amount of memory is adequate.

advance warning warning The message presents an advance warning.The message presents a warning.

after a period of after After a period of ten minutes, check the file.After ten minutes, check the file.

alternative choices alternatives The application gives you two alternative choicesThe application gives you two alternatives.


and also and It creates the table, the heading, and also the row.It creates the table, the heading, and the row.

are different differ The trustee IDs are different. The trustee IDs differ.

any given example any example Any given example is helpful to usersAny example is helpful to users.

are present in, is present in

in This applies to reports that are present in the Reports folder.This applies to reports that are in the Reports folder.

arrive at a decision decide We need to arrive at a decision.We need to decide.

as a means of to Select the DN as a means of identifying the user.Select the DN to identify the user.

as a result of because The application crashed as a result of…The application crashed because…

as to where about where We need to supply information as to where the files are located.We need to supply information about where the files are located.

as to whether whether You need to decide as to whether you will accept the offer.You need to decide whether you will accept the offer.

as well as and; and also Plan for the upgrade as well as install it.Plan for the upgrade and install it.

at a later date later The beta release will happen at a later date.beta release will happen later.

at the present time, presently

now Synchronization is not available at the present time.Synchronization is not available now.

at the time when when The files were stored at that location at the time when you renamed it.

The files were stored at that location when you renamed it.

at this point in time now Login is not possible at this point in time.Login is not possible now.

at this time now It cannot be deleted at this time.It cannot be deleted now.

by means of by, by a, through Each method is introduced by means of two short checklists.Each method is introduced by two short checklists.

By means of modules, Apache can be expanded.Apache can be expanded through modules.

by use of by, by using Data can be transferred over a LAN or WAN by use of Ethernet technologies.

Data can be transferred over a LAN or WAN by using Ethernet technologies.

changes occurring in changes in Changes occurring in the Content Management repository...Changes in the Content Management repository…



completely finished finished After the query has completely finished processing, the results are available...

After the query has finished processing, the results are available...

component parts parts, components

Ensure that you have the component parts before you begin.Ensure that you have the components before you begin.Ensure that you have the parts before you begin.

connected together connected Web services are business logic components that can be connected together and exchange data.

Web services are business logic components that can be connected and exchange data.

does not change at all does not change

The screen display does not change at all.The screen display does not change.

during the course of during New definitions might be released during the course of the day.New definitions might be released during the day.

each and every every The replica ring of each and every partition...The replica ring of every partition...

each individual each Each individual option must be selected separately.Each option must be selected separately.

eliminate altogether eliminate Eliminate the extra keystrokes altogether.Eliminate the extra keystrokes.

exactly the same identical The name must be exactly the same as the LDAP attribute...The name must be identical to the LDAP attribute...

exhibits a tendency to tends to The application exhibits a tendency to close unexpectedly.The application tends to close unexpectedly.

for a length of time for a time The providers share the identifier for a length of time.The providers share the identifier for a time.

for the purpose of to Users authenticate to the server for the purpose of managing a job.Users authenticate to the server to manage a job.

for the reason that because Do not use this function for the reason that it is deprecated.Do not use this function because it is deprecated.

fully finished finished Wait until development is fully finished.Wait until development is finished.

give consideration to consider You should give consideration to certification.You should consider certification.

gives answers to answers The FAQ gives answers to most questions.The FAQ answers most questions.

has the ability to can Insert an object that has the ability to retrieve passwords.Insert an object that can retrieve passwords.

have a need for need If you have a need for multiple tiers of pooling...If you need multiple tiers of pooling…



having to do with about Subsequent pages having to do with the functionality...Subsequent pages about the functionality...

in back of behind The first graphic appears in back of the dialog box.The first graphic appears behind the dialog box.

in conjunction with with You can use keyboard shortcuts in conjunction with the menus.You can use keyboard shortcuts with the menus.

in case of, in the case of

Depending on context, use “for” or “if there is”

Use this to avoid the active mode in case of scripting.Use this to avoid the active mode for scripting.

In case of corruption, you can restore from the backup.If there is corruption, you can restore from the backup.

in length long The document is two pages in length.The document is two pages long.

in many cases often, usually In many cases, you need to select more options.You usually need to select more options.You often need to select more options.

in most cases generally, usually

In most cases, the default options are sufficientThe default options are usually sufficient

in situations when when The commands are used in situations when you need to...Use the commands when you need to...

in the area of in, for, of Key benefits in the area of web services include...Key benefits of web services include...

in the course of during A process sends email in the course of its execution.A process sends email during its execution.

in the event of

in the event that

if, when In the event that the JVM encounters an error...If the JVM encounters an error...

in the interests of for This is done in the interest of backward compatibility.This is done for backward compatibility.

is able to can If iManager is able to access the server…If iManager can access the server…

is at present is This option is at present unavailable.This option is unavailable.

is dependent on depends on Wpsd.nlm is dependent on it.Wpsd.nlm depends on it.

is present in is in A private key is present in the keystore.A private key is in the keystore.

is used to show, is designed to show

shows Alt+F4 is used to show output from the modules.Alt+F4 shows output from the modules.

it is because of this that

because of this It is because of this that the command fails.Because of this, the command fails.



joined together joined The rows are joined together.The rows are joined.

located within located in The options are located within the dialog box.The options are located in the dialog box.

longer period of time longer time Increase the value to use a longer period of timeIncrease the value to use a longer time.

make use of use How do I make use of SITE commands?How do I use SITE commands?

means through which way that This provides a means through which default behaviors can change.This provides a way that default behaviors can change.

on the subject of on The document contains information on the subject of…The document contains information on…

once and only once once A message is delivered once and only once.A message is delivered once.

reasons why reasons The reasons why you should use the application are listed…The reasons you should use the application are listed…

referred to as called This is referred to as the Trusted Root.This is called the Trusted Root.

return control back return control The NLM program should return control back to NetWare.The NLM program should return control to NetWare.

shows a list of lists The following figure shows a list of eight resources.The following figure lists eight resources.

or

There are eight resources.

take action act, do You are prompted to take action if the conditions are true.You are prompted to act if the conditions are true.

take into consideration consider You should also take into consideration the attachments.You should also consider the attachments.

the extent to which how much The extent to which you must configure OSPF depends on...How much you must configure OSPF depends on...

the fact that that I'm surprised by the fact that the report is incomplete.I'm surprised that the report is incomplete.

through the use of through Software is distributed through the use of bundles.Software is distributed through bundles.

to a large extent largely, mostly Configuration is done to a large extent by using YaST.Configuration is done mostly through YaST.

until such time as until Data written to files is held in cache until such time as it would be normally written.

Data written to files is held in cache until it is normally written.



3.12 Potentially Troublesome WordsThe lists in this section identify the appropriate spelling, spacing, hyphenation, and case of potentially troublesome words that do not appear in Section 3.2, “Terminology Spelling and Usage,” on page 77. For product-specific terms, see Appendix D, “Product Terminology,” on page 275.

3.12.1 AAAI (Application to Application Interface) address space address space identifier (ASID) algorithm alias all right (instead of alright) alpha application ID asynchronous communication awhile (adv)

3.12.2 Bbackground image backlog batch beta binary binary data binary synchronous black-and-white (adj) Boolean (adj) breakpoint build time

whether or not whether Specify whether or not to start the application.Specify whether to start the application.

with the exception of except for With the exception of the timeout value, you don't need to modify the settings.

Except for the timeout value, you don't need to modify the settings.

work together with work with NetworkManager cannot work together with SCPM.NetworkManager cannot work with SCPM.


A B C D E F G H I J

K L M N O P Q R S T

U V W X Y Z


button bar buzzword byte-stream

3.12.3 Ccash flow CD-ROM checkpoint checksum character set class clipboard commonplace commonsense (adj) companywide compile time (n) compile-time (adj) component computer-aided (adj) concatenation connector cross-section

3.12.4 Ddaemon daisy chain (n), daisy-chain (v, adj) DASD (Direct Access Storage Device) data integrity data item data name data source data set data structure data type database deployment dereference detached instance DHTML direct-connect disk-based (adj) DOS double-check (v) double-density double-sided


downgrade (v) downtime DTD (Document Type Definition) dump

3.12.5 Eend-user (adj) encoding environment event event-driven

3.12.6 Ffixed-point (adj) fixed-width (adj) (instead of fixed-pitch or monospace) float floating-point focus foreign key forms FTP full-length full-screen (adj) function key

3.12.7 GGUI (graphical user interface)GUID (globally unique identifier)

3.12.8 Hhandshake, handshaking (instead of hand-shake or hand-shaking) height (not heighth) heuristic hexadecimal high-level (adj) high-resolution (adj) high-speed (adj) home page hook hotspot


3.12.9 II/O ID (for identification) in-between (adj), in between (adv or prep) in-depth (adj) in-house (adj) inheritance inline input/output instance integer interface inter-language intranet italic (adj), italics (n)

3.12.10 JJavaDoc JavaServer Page

3.12.11 Kkey binding keycap keycode keymap, keymapping keypad keystroke keyword

3.12.12 LLDAP (Lightweight Directory Access Protocol) lifecycle loopback low-level (adj) lowercase

3.12.13 Mmainframe makefile many-to-many (database terminology) many-to-many relationship many-to-one relationship


markup (n, adj) markup language Micro Focus multi-tasking

3.12.14 NNational Language Support .NET Framework (instead of .NET Development Framework) nonnumeric nonzero null-terminated string numeric-edited

3.12.15 Oobject one-to-few one-to-many (database terminology) one-to-many relationship one-to-one online optimization overlaid (normal English meaning) overlayed (divided into overlays)

3.12.16 Pparameter part-time Perl (instead of PERL) pick file pick list PL/I (Programming Language 1) preventive (instead of preventative) primary key printout (n) pull down (v) pull-down (adj, n) – Do not use. Use list box instead. pulldown (adj, n)

3.12.17 QQ&A


3.12.18 Rread-only (adj) read-write (adj) reallocate reboot record reentrant reexamine referential integrity (RI) rekey relationship return code rightmost round-robin distribution run-time system run-time tunable run unit

3.12.19 Sshareable shared run-time system single-density SNMP (Simple Network Management Protocol) SOAP (Simple Object Access Protocol) spreadsheet SQL (Structured Query Language) state-of-the-art system subprogram subsystem synchronous communication

3.12.20 Ttime frame timeout timesharing to-do list topmost trace typeable typecasting typeface typestyle third-generation programming language (3GL)


3.12.21 UunderscoreUNIX

3.12.22 Vvalid vice versa

3.12.23 WW3C (World Wide Web Consortium) worldwide (adj) wildcard work area workaround (n) workflow workforce workgroup workload workspace workstation wraparound WSDL (Web Services Description Language)

3.12.24 Xx-axis x-coordinate x-height XHTML (Extensible Hypertext Markup Language)XML entity XML schema XML stream XPath XSLT (Extensible Stylesheet Language Transformations)

3.12.25 YYubiKey

3.12.26 Zzeros



II IIOrganization and Formatting

Organization and formatting define the framework for your writing. Organization elements include headings, paragraphs, lists, graphics, tables, and so on. Formatting conventions establish logical and visual consistency within and across doc sets. With effective structured authoring, writers can exchange, reuse, or publish content to multiple formats and across deliverables. Information has a predictable appearance, sequence, and location, which makes it easier for users to find, understand, and use.

Follow the organization and formatting guidelines to develop and present structured information that is easy to locate, read and follow.

Chapter 4, “Product Documentation,” on page 143 Chapter 5, “Computer Elements,” on page 151 Chapter 6, “Mobile Device Elements,” on page 175 Chapter 7, “Cross-References,” on page 177 Chapter 8, “Headings,” on page 181 Chapter 9, “Graphics,” on page 185 Chapter 10, “Lists,” on page 189 Chapter 11, “Procedures,” on page 195 Chapter 12, “Tables,” on page 203 Chapter 13, “Legal Notice,” on page 207 Chapter 14, “Accessibility (Section 508),” on page 211

Organization and Formatting 141

142 Organization and Formatting

4 4Product Documentation

Product documentation should follow the guidelines in the other sections of the Style Guide, with the exceptions and differences listed in this section.

Section 4.1, “Structured Authoring,” on page 143 Section 4.2, “Product Names,” on page 144 Section 4.3, “Software Requirements,” on page 145 Section 4.4, “Prerequisites,” on page 146 Section 4.5, “Product Release Types and Version Numbers,” on page 147 Section 4.6, “Versions, Patch Updates, and Service Packs,” on page 148 Section 4.7, “Previous Releases,” on page 149 Section 4.8, “Future Functionality,” on page 149 Section 4.9, “Examples,” on page 149

4.1 Structured AuthoringStructured authoring is an method of analyzing, organizing, and displaying content that supports reader comprehension and content reuse. You develop content using a structured authoring tool to define and enforce a consistent organization of information in documents.

Structured authoring tools enable writers to identify the building blocks of content, such as headings, paragraphs, lists, graphics, and tables, by wrapping them in XML tags. Advanced authoring features identify parts of the content that have different purposes, so content can be reused and combined in different ways to produce different outputs. The markup tags ensure that the content can be output in with the same look-and-feel, regardless of the authoring tool used to create it. The publishing style sheet for the documentation website controls the display format of the final output.

Micro Focus writers use various structured authoring tools that support DITA or DocBook vocabularies. The authoring systems use a document type definition (DTD) to describe the content structure and specify which elements can contain other elements, which elements are optional, and which are required.

NOTE: Different authoring tools can impose different constraints on the content development environment. Refer to your authoring tool guide for information about using the tools.

Follow these authoring guidelines to structure content:

Analyze the users to determine what tasks they need to perform. Analyze the product to determine what users need to know in order to perform those tasks.

User-centric documentation answers four questions for users*: Why should I care? What is it? How do I do it? Why did it do that?

Product Documentation 143

* Source: Bonni Graham, The 4 User Questions.

Present clear, concise, and consistent information that is easily read and scanned by using the following content presentation strategies: Sentences are simple and direct, with no more than 20 words. Paragraphs group 3 to 5 related sentences. Sections group only 3 to 5 related paragraphs, or subdivide the ideas with headings. Details are consumable by organizing them in effective, coherent, and meaningful ways:

Lists (simple, bulleted, checklist) Procedures Tables Graphics (conceptual illustrations, diagrams, flow charts, graphs, charts, infographics,

and so on) Videos (conceptual overviews, feature demonstrations, task tutorials, and so on)

Organize and format content to have a predictable appearance, location, and sequence. Benefits include: Multiple authors can develop content for a doc set, yet provide a seamless experience for

readers. Authors can exchange, reuse, or publish content to multiple formats and across

deliverables. Users learn what to expect, which makes information easier for them to find, understand,

and use.

4.2 Product Names When possible, use the single-source process for product names that is available in your

authoring tool. Do not use possessives in product names. In general, do not abbreviate the name of a product, tool or utility; always spell its name in full.

For example, use the Mainframe Access reuse tag instead of typing MFA. If the repetition of the full name impairs readability, consider alternatives as an exception to branding guidelines for marketing: Use a shortened name option. Get the shortened name approved by the program manager. Use an abbreviated name option. Get the abbreviation approved by the program manager. Use the full name in the first instance in the topic. Thereafter use the shortened or

abbreviated name in that topic. Apply the usage consistently throughout the document. Avoid over-advertising. Do not thrust the Micro Focus names and product names constantly at

the reader. Except where necessary for clarity, do not mention Micro Focus. Instead use phrases like this COBOL system or the requirements module in the ALM suite.

144 Product Documentation

https://www.slideshare.net/bonnigraham/document-to-the-question

4.3 Software RequirementsSoftware requirements should list all supported versions of third-party software at the time of the release. Third-party software includes operating systems and applications.

If Customer Care maintains your support matrix for third-party software products, insert a standard sentence referring users to the Supported Products page of the Support website for the most current software requirements information.

List software in reverse chronological order, starting with the newest release. Group operating systems by server and desktop. For Windows operating systems, treat “R2” as a separate operating system. Beginning with Windows Server 2008 R2, Windows does not offer a 32-bit version. Because 64-bit is the only option, you do not need to document that we support 64-bit.

If your product’s support matrix assumes support for all service packs, do not list a specific service packs unless a minimum service pack is required. If a minimum service pack is required, state the minimum requirement and use “or later.”

If your product’s support matrix does not assume support for all service packs, list them specifically. If a patch level is required, include the information.

Assume support for all editions, such as Standard, Enterprise, and Datacenter. Do not list editions unless only a specific edition is supported.

Example: For the most recent information about third-party software requirements, see the AppManager Supported Products page at www.netiq.com/support/am/supportedproducts/.

Example: Windows Server 2016Windows Server 2012 R2Windows Server 2012Windows Server 2008 R2Windows Server 2008 (32-bit and 64-bit)Windows 10 (32-bit and 64-bit)Windows 8.0, 8.1 (32-bit and 64-bit)Windows 7 (32-bit and 64-bit)

Example: Windows Server 2008 SP1 or later

Example: Windows XP SP2 or later

Example: Windows 8 and 8.1

Example: Red Hat Enterprise Linux (RHEL) 6.7, 6.8, 7.1, and 7.2

Example: SUSE Linux Enterprise Server (SLES) 12 SP1 with the latest patch updates applied

Example: VMware vCenter 6.0 (U1 and U2)


https://www.netiq.com/Support/am/supportedproducts/

Document the supported architectures in parenthesis at the end of the product name if they are essential to your product’s support matrix.

If the Itanium architecture is supported, include it after the parenthetical information.

If you must use a version number, use either method: Version number

Internet Explorer 6.1 Microsoft Windows NT 5.0

Year of release Microsoft Office for Windows 95 Microsoft Outlook 97

Specify third-party product version numbers only on the first mention in a topic and only if it is relevant. During subsequent mentions, refer to the product name without the version number or date designation, such as Windows NT Server, unless it is needed for clarity.

Avoid specifying a version number or date designation within the body of text. Use .x to indicate all release numbers of a product, such as Windows NT Server 3.x. Do not use

the terms higher or lower to indicate earlier or later releases. Instead, use the terms earlier or later, such as Windows NT version 3.0 or later.

4.4 Prerequisites Use checklists for most lists of prerequisites. You can use tables for prerequisites if the information is complicated or needs a matrix type of

presentation.

For more information about how to list software requirements, see Section 4.3, “Software Requirements,” on page 145.

Example: Microsoft SQL Server 2014 Express Edition

Example: Windows Server 2008 R2 Server Core

Example: Windows 8 Pro (desktop mode only)

Example: Windows 7 (Professional and Ultimate)

Example: Windows Server 2008 (64-bit)

Example: Windows Server 2003 R2 (32-bit and 64-bit)

Example: Windows Server 2003 (32-bit and 64-bit), including Itanium (64-bit, Enterprise and Data Center)


4.5 Product Release Types and Version NumbersMicro Focus products use the following release types and version increments:

Release Type Description Documentation Version

Major Full release of substantial new product functionality:

new features

database changes

architectural changes

version compatibility

Includes multiple bug fixes.

Includes cumulative changes introduced in all interim releases of the same product since the last major release.

Release Notes

Doc updates for related features and enhancements

X.0

Minor Includes complementary functionality to functions found in the major release.

Includes smaller-scope new product functionality.


Includes cumulative changes introduced in interim releases of the same product, such as minor releases, service packs, patch updates, hotfixes, and FTFs.

Release Notes

Doc updates for related features and enhancements

X.#2017 R#

Service Pack Includes back-end enhancements unseen to the user.

Includes platform support updates.


Includes cumulative changes introduced in interim releases of the same product, such as service packs, patch updates, hotfixes, and FTFs.

Release Notes

Doc updates for critical issues

X.X.#X.X SP #X.X Service Pack #

Patch Update Is smaller than other increments, but bigger than a hotfix.


Includes cumulative changes introduced in interim releases of the same product, such as patch updates, hotfixes, and FTFs.

Readme P#Patch #

X Patch #X.X Patch #X.X.X Patch #

Hotfix Includes resolutions for one or more specific customer problems or security vulnerabilities.

Includes cumulative changes introduced in interim releases of the same product, such as hotfixes, and FTFs.

Readme X.X.X.#X.X.X Hotfix #


You must include product version numbers in the document title of Release Notes.

Include the product version number for the Help Welcome page. Include the product version number for the PDF title page. Include product version numbers in references to third-party product releases in a System

Requirements section or other section that addresses specific versions. See Section 4.3, “Software Requirements,” on page 145.

4.6 Versions, Patch Updates, and Service PacksWhen you give software and hardware requirements for your product, ensure that you accurately represent which versions are necessary, especially with third-party products. An open-ended statement such as “Use Windows Server 2003 and later” can imply that our products always work with the latest versions of third-party products, which might not be correct. For many products, the only way to ensure accuracy is to list all supported versions. For more information about listing all supported versions for third-party software, see Section 4.3, “Software Requirements,” on page 145.

If you use an open-ended reference, use the word “later” or “latest” instead of “higher,” “greater,” or “newer.”

If you do use this type of reference, ensure that it has been tested and verified with product development and product management, and ensure that you recheck the accuracy for each documentation release.

If you are discussing a starting point for certain features or functionality that entered use with a service pack, use “beginning in” or “beginning with:”

Field Test File Includes a targeted solution to resolve a customer problem or security vulnerability.

Delivered directly to a customer to verify a fix in a specific environment.

Readme provided by Engineering or Tech Support

FTF

Example: Filr 3.1 Release Notes

Example: NetIQ CloudAccess 2.1.1 Patch 1 Release Notes

Release Type Description Documentation Version

Example: You must use iManager 2.7 or later.

Example: Use Windows Server 2012 R2 with the latest service pack applied.

Example: Beginning in OES 2 SP3, the Domain Services for Windows Provisioning Wizard does not transfer the master replica.

Example: Beginning with OES 11 SP1, the OES Samba package replaces the base Samba packages.


4.7 Previous Releases Refer to previous product releases only in Upgrading... and Migrating... sections that address

server compatibility issues. Otherwise, use the Release Notes as the primary document for referencing previous Micro Focus releases.

To refer to a previous, non-Micro Focus product release in a System Requirements section or other section that addresses specific versions, follow the guidelines for referencing product names in Section 4.3, “Software Requirements,” on page 145.

4.8 Future Functionality In general, do not make promises about future functionality or the future removal of existing

functionality. A deprecated software feature might remain in the release along with a preferred alternative

software feature. Deprecated status implies an intent to obsolete the software feature in the future. Include a notice only in the Release Notes about the deprecated software feature. Include information about the exact release for obsoleting the feature only when the exact release version are known, eminent, and confirmed by the program manager.

4.9 ExamplesApply the following guidelines to the examples you create for inclusion in your documentation. Examples can be included as part of running text, in a procedure step, or as a separate section.

Consider creating a separate section for examples that are longer than five or six lines. You can include counter-examples or examples that point out common errors or misconceptions.

In such cases, make it clear that the material is a counter-example. For example, you can use a separate section titled “Common Mistakes.”

Do not use the real names (first and last), or the phone numbers, extensions, mailstops, passwords, TCP/IP addresses, URLs, user IDs, or email addresses of actual employees in your screen shots, scripts, contexts, trees, or other examples. Do not use real workstation, server, directory, or directory tree names. Doing so creates a high security risk.For a list of some sample TCP/IP addresses and URLS, see Section 5.4.5, “IP Addresses,” on page 159 and Section 5.4.12, “URLs or Domain Names,” on page 161.For information about example telephone numbers, see Section 1.34, “Telephone Numbers,” on page 57.

Example: systemd: The NFS Mount Option bg Is Deprecated

The upstream developers of systemd no longer support the NFS mount option bg. SLE 12 SP2 still supports the bg mount option; however, the option will be removed in the next version of SLE. It will be replaced by the systemd mount option nofail.

Example: NTP Query Program ntpdc Is Obsoleted

After being deprecated in releases for several years, the Network Time Protocol Query program ntpdc.has been replaced with ntpq in SLE 12 SP2. The ntpdc daemon is disabled by default for security reasons. You can re-enable ntpdc by adding the line enable mode7 to /etc/ntp.conf, but preferably you should use ntpq instead.


Do not use the word “test” in your graphics (such as “test server”). After choosing a set of appropriate or approved names for your examples, use them consistently

throughout your documentation. For a list of approved international names, see “User Names” on page 64.


5 5Computer Elements

Follow these guidelines for presenting information about computer elements.

Section 5.1, “Case Sensitivity,” on page 151 Section 5.2, “Graphical User Interfaces,” on page 152 Section 5.3, “Keyboard Keys,” on page 157 Section 5.4, “Network and Computing Elements,” on page 158 Section 5.5, “Storage Elements,” on page 162 Section 5.6, “Command Line and Prompt,” on page 166 Section 5.7, “Commands,” on page 166 Section 5.8, “Parameters,” on page 170 Section 5.9, “Screen Displays and System Responses,” on page 171 Section 5.10, “Software Components in Running Text,” on page 171 Section 5.11, “Source Files,” on page 172

5.1 Case SensitivityCase-sensitive software distinguishes between uppercase and lowercase.

Document case-sensitive software carefully. When a command is entered in the wrong case in case-sensitive software, the command fails.

For example, the UNIX operating system is case sensitive. The UNIX awk command has two command options: -F and -f. The -F option lets you specify a field-separator character. The -f option lets you specify a file name. You must use the proper case when you enter the awk command, the option you want, and the value of the option.

Present directory names, file names, and commands in lowercase unless you are documenting case-sensitive software (such as Linux or UNIX). If you are documenting case-sensitive software, present the directory names, file names, and commands exactly as they appear in the software.

If the software you are documenting runs on multiple platforms, or if you are not sure what platform it will run on, treat directory names, file names, and command names as if they are case-sensitive.

For specific examples, see the following sections:

“Commands” on page 166 “Servers” on page 161 “Hosts” on page 159 “Drives” on page 163 “Volumes” on page 164 “Directories” on page 164 “Files” on page 165

Computer Elements 151

5.2 Graphical User InterfacesFollow these guidelines when you document GUI interfaces.

Section 5.2.1, “Menus and Options,” on page 152 Section 5.2.2, “Tabs,” on page 153 Section 5.2.3, “Check Boxes,” on page 154 Section 5.2.4, “Buttons,” on page 154 Section 5.2.5, “Icons,” on page 155 Section 5.2.6, “Group Boxes,” on page 155 Section 5.2.7, “Ribbons,” on page 156 Section 5.2.8, “Tables or Tabular Lists,” on page 156

5.2.1 Menus and Options Present menu names as they appear in the software. Present menu options and dialog box options exactly as they appear in the software, and tag

them with the appropriate element in your authoring tool.

When a menu option includes an ellipsis, omit it from the option in running text.

Present menu and dialog box options as they appear in the software.

Use the appropriate element in your authoring system to identify menu names and dialog box options.

In most cases, use field names or menu names instead of saying “field” or “menu.”

When possible, refer to dialog box options without identifying them as tabs, buttons, or boxes. However, you should be specific if it is necessary for clarity, such as when there are many choices within a dialog box, or choices with similar names, or when the context might not be immediately available or obvious to the user. Depending on the context, you might use any of the following:

Example: Click Edit a File to change the wording of your document.

Example: Transaction file name lets you specify the location of your transaction files.

Example: If the menu option reads “Save As…”, the text reads as follows:

Click Save As to save the file in another directory.

Example: Click Edit a File to change the wording of your document.

Example: Transaction file name lets you specify the location of your transaction files.

Example: Select File > Print.

Example: Select Query-Based Group.

Example: Click Prepare eDirectory.

152 Computer Elements

Use the following guidelines for interface terms in prepositional phrases: For most things that are three-dimensional in the “real world,” use “in.”

In the dialog boxIn the windowIn the pane

For most things that are two-dimensional in the “real world,” use “on.”

On the pageOn the screen

Exceptions to the two-dimensional/three-dimensional guideline:

In the columnAt the workstationAt the server

When you tell the user to perform a procedure in an application, use “in.”

In eDirectory, select the User object.In iManager, click Roles and Tasks.

5.2.2 TabsA “tab” is the tabbed title that you click; it is not the property page or dialog box that opens. Depending on context, you could use any of the following:

Menu-to-tab navigation:

Navigation through successive tabs:

Example: Select from the following options: [a list of check box items]

Example: Select Enable, then change the setting. [a check box]

Example: Select the Database URL option button. [an option button]

Example: Select Database URL. [an option button]

Example: Select one of the options. [a list of radio buttons]

Example: Specify settings for each field: [a series of text boxes or drop-down lists where users select settings or provide text]

Example: Click Apply. [a command button]

Example: Click the Create New Mail button. [a button with a graphic and no text]

Example:Click . [a button with a graphic and no text]

Example: Click the Add button in the lower left corner. [a button in a non-standard location or in an especially crowded dialog box.]

Example: Click Environment > General

Example: Click SMTP/MIME > ESMTP Settings.


Navigation when you start with the tab:

Some tabs have lists of additional items on the tab. If possible, refer to the items only by name; if it is necessary for clarity, refer to the “list” or “drop-down list,” depending on functionality.

5.2.3 Check BoxesYou should usually refer to check boxes by their label names instead of calling them “check boxes.” If you must refer to them by the generic name, call them “check boxes,” not “boxes.” Use “select” or “deselect” as the verb.

5.2.4 Buttons Option buttons/radio buttons: You should usually refer to option buttons by their label names

instead of calling them “buttons.” If you must refer to them by the generic name, call them “option buttons” for a Windows interface or “radio buttons” for a Linux interface, but not just “buttons.” Use “select” or “deselect” as the verb.

Command buttons: A command button is a window or dialog box control that causes the application to perform some sort of action when the control is clicked, such as OK, Apply, or Print. A command button can have a text label, a graphic, or both. When the button is clicked, it displays feedback to the user by showing a pressed-in appearance. Use “click” as the verb. You should usually refer to a command button by its text label instead of calling it a “button.”

Example: Click XYZ

Example: Click the XYZ tab

Example: Click General, then select Settings.

Example: Click the General tab, then select Settings from the drop-down list.

Wrong: Check the box.

Wrong: Mark the check box.

Right: Select Update.

Right: Alternate usage if necessary for clarity:

Select the Update check box.

Right: Alternate usage if the check box is selectable but the text is not:

Select the check box next to the server name.

Wrong: Select the Current Page button.

Right: Select Current Page.


Select the Current Page option button.


If a well-known command button has a graphic but no text label, you can use just the button name.

If it is necessary for clarity, such as for a less well-known button with a graphic and no text label, you can use the word “button” or include an inline figure of the button’s graphic.

Expand/collapse buttons: An expand button allows users to expand or collapse a list or other structure to view or hide subentries. When you expand a collapsed list or structure, the corresponding expand button appears as a downward-facing triangle. When you collapse an expanded list or structure, the button appears as a right-facing triangle. If an expand button is named, include the name in the documentation. If an expand button is not named, use the term expand button and describe its location.

5.2.5 IconsAn icon is a nonfunctional, two-dimensional element that exists for display purposes only. Use the lowercase term “icon” when an element or item is nonfunctional. Name the icon when you refer to it.

5.2.6 Group BoxesA group box is an area in a dialog box where similar options are grouped together. A group box has a frame or line around it, and a title within the frame. In most cases, you can use just use the title if you need to refer to the area, instead of referring to it as a box.

Wrong: Click the OK button.

Right: Click OK.

Wrong: Click the Print button.

Right: Click Print.

Right: Click the Create New Mail button.

Right: Click to view details

Example: Click the Properties expand button to hide the properties.

Example: Click the expand button at the bottom of the menu to show additional menu items.

Example: The Health icon is green.

Right: Select a Mail and Phone option.


In the Mail and Phone group box, select an option.


5.2.7 RibbonsA ribbon interface comprises different groupings of commands and options, such tabs, groups, galleries, and others, as shown in the figure below:

To write user navigation for the ribbon, use the following convention:

1. Choose Page Layout tab > Page Setup group > Breaks > Page.

Use "tab" and "group" to differentiate the areas of the ribbon.

5.2.8 Tables or Tabular ListsA table or tabular list presents data by rows and columns. The intersection of a row and column is a cell.

If possible, refer to the display by the table or list name.

A column is the vertical arrangement of data within a table. Use the term “column” to describe the vertical arrangement of cells within tables.

A column heading is the title of a column of data in a table. Column headings sometimes invoke additional actions, such as sorting items or displaying a lit of items.Use the phrase “column heading” to describe the title of a column or to refer to elements that invoke additional actions.

Use the term “row” to describe the horizontal arrangement of cells within tables.

Example: Resources are displayed in the Assigned Resources table.

Example: The Name column displays backlog items.

Example: Click the Created On column heading to sort the items by the creating date.

Example: The Backlog Item row displays the item number and description.


Within a table, a “cell” is a box that results from the intersection of a row and a column. A cell does not need to contain data. When a box is empty, refer to the area as a cell. When a box contains text, refer to it by name.

The phrase items in a table refers to data within the cells of a table. If possible, name the item. Otherwise, use the phrase item in a table.

5.3 Keyboard Keys In general, use the key name only. Do not add the word “key.”

Capitalize the first letter of the key name. Do not use any authoring system elements to mark up key names.

Section 5.3.1, “Arrow Keys,” on page 157 Section 5.3.2, “Spacebar,” on page 157 Section 5.3.3, “Capitalization and Spelling of Common Key Names,” on page 158 Section 5.3.4, “Key Combinations,” on page 158

5.3.1 Arrow Keys When you refer to an arrow key, hyphenate the key name and capitalize the first letter of the first

word. Do not capitalize the word “arrow” when it is used as part of a key name.

Do not use a symbol for an arrow key in text. If you are referring to an arrow as an interface element instead of a key name, do not capitalize

any part of the name.

5.3.2 SpacebarUse the definite article when referring to the Spacebar. The first letter of the word “Spacebar” is capitalized. “Spacebar” is always one word.

Example: The Changed By column displays the value Stan.

Example: Select an item in the table.

Example: Pause over an item in the IP Address column to view details about the server.

Example: Type your password and press Enter.

Example: Press the Right-arrow.

Example: Click the down-arrow to display a list of options.


5.3.3 Capitalization and Spelling of Common Key NamesThe following list shows acceptable capitalization and spelling of commonly used key names. Use the form presented in the list even if it does not match the key label on your keyboard.

5.3.4 Key Combinations When individual keys must be pressed simultaneously, join the key names with the plus sign (+).

When individual keys must be pressed sequentially, use the greater-than sign (>) between the key names.

5.4 Network and Computing ElementsFollow these guidelines for network and computing elements in documentation procedures and examples:

Section 5.4.1, “Domains,” on page 159 Section 5.4.2, “Email Addresses,” on page 159 Section 5.4.3, “Hosts,” on page 159 Section 5.4.4, “HTML or XML Elements,” on page 159 Section 5.4.5, “IP Addresses,” on page 159 Section 5.4.6, “Paths,” on page 160 Section 5.4.7, “Registry Entries,” on page 160 Section 5.4.8, “root,” on page 160 Section 5.4.9, “Servers,” on page 161 Section 5.4.10, “Telephone Numbers,” on page 161 Section 5.4.11, “Time Servers,” on page 161 Section 5.4.12, “URLs or Domain Names,” on page 161 Section 5.4.13, “Users,” on page 162 Section 5.4.14, “Utilities and Programs,” on page 162

Alt Enter PageDown Spacebar

Backspace Esc PageUp Tab

Ctrl Insert Plus (+) Up-arrow

Del Left-arrow Right-arrow

Down-arrow Minus (-) Shift

Example: Press Shift+Right-arrow to move through the table.

Example: Press Ctrl+Alt+Del to reboot the workstation.

Example: Press Shift+click to select all entries in the added address book.

Example: Press Esc > Enter to return to the main menu.


5.4.1 DomainsDo not use real domain names. Doing so creates a high security risk. In addition, avoid using trademarked names, celebrity names, names of popular fictional characters, and names of public figures as example domain names.

Replace operational domain names with domain names reserved for use in documentation. For some examples, see Section 5.4.12, “URLs or Domain Names,” on page 161.

5.4.2 Email AddressesDo not use real email addresses in your documentation or screen shots. Doing so creates a high security risk. In addition, avoid using trademarked names, celebrity names, names of popular fictional characters, and names of public figures as example email addresses.

See Section 1.3, “Addresses,” on page 24 for information about formatting addresses.

5.4.3 HostsPresent host names in lowercase unless you are documenting case-sensitive software.

5.4.4 HTML or XML ElementsWhen you discuss an example HTML or XML element as it is presented in actual HTML or XML output, use the tags in your authoring system to present it in a monospace font.

5.4.5 IP Addresses Do not use actual company IP addresses. Because company IP addresses use a public IP

addressing scheme, they can be directly accessed across the Internet, and it is a security risk to reveal them.

Use IP addresses that follow IP addressing rules. For IPv4, each number (one to three digits between the periods) can be no more than 255, which is one byte.The following list gives some standard private IPv4 address domains that are commonly used as examples of different classes of networks. It is safe to use them in examples because, as private addresses, they are not routed on the Internet. (Always replace each x with a valid value from 0 to 255.) Class A network: Medium to large enterprise (up to 16,777,214 hosts).

IP Address: 10.0.0.0Network Mask: 255.0.0.0Class Range: 10.x.x.x

Class B network: Small to medium enterprise or headquarters office (up to 65,534 hosts).

Example: Copy your files to aus-market.

Example: The <replacement-data> element can appear as a child of the <message> element under a Subscriber channel <mail> element.

Example: Use a Sect1 element to create a first-level heading in your document.


IP Address: 172.16.0.0Network Mask: 255.240.0.0Class Range: 172.16.x.x to 172.31.x.x

Class C network: Small office or branch office (up to 254 hosts).

IP Address: 192.168.0.0Network Mask: 255.255.255.0Class Range: 192.168.x.x

Loopback device: A special address that resolves to localhost.

IPv4 Address: 127.0.0.1IPv6 address: ::1

5.4.6 Paths Use a backslash (\) as the delimiter between elements in path names unless the software you

are documenting requires forward slashes.

If you are documenting a multi-platform product in which a single path name could use either backslashes or forward slashes, depending on platform, present the path name with backslashes.

5.4.7 Registry EntriesWhen you give the path or name of a registry key, use the tags in your authoring system to present it in a monospace font.

5.4.8 root In Linux documentation, use the SystemItem element to mark references to root.

In non-Linux references, do not use any markup.

Example: Copy the files into the account\receive\reports directory.

Example: Verify that the DHCP option you have created is being used for the Middle Tier address by looking for the value in the HKLM\Software\ZENworks registry key at the workstation.

Example: If you started the Monitor Agent as root, then you must be logged in as root to stop it.

Example: Ensure that you are logged in as root.

Example: If the installation program does not start automatically, run setup.exe from the root of the CD.


5.4.9 Servers Present server names in the case in which they appear in the software. Do not use real server names in your documentation or screen shots. Doing so creates a high

security risk. In addition, avoid using trademarked names, celebrity names, names of popular fictional characters, and names of public figures as example server names.

5.4.10 Telephone NumbersFor guidelines on using telephone numbers in your documentation, see Section 1.34, “Telephone Numbers,” on page 57.

5.4.11 Time ServersDo not use the DNS name or IP address of a real company NTP time server. Use private IP addresses in the examples, as described in Section 5.4.5, “IP Addresses,” on page 159.

You can alternatively use a public time server such as the NIST time servers provided by the NIST Internet Time Service (http://tf.nist.gov/tf-cgi/servers.cgi). The site lists the DNS names and IP addresses of global and regional time servers that NIST provides.

5.4.12 URLs or Domain NamesFor guidelines on formatting URLs, see Section 1.3.2, “Internet Addresses (URLs),” on page 24.

Do not use real URLs or domain names in your documentation. For example, you shouldn’t use www.mycompany.com, because it is a is a real URL for a domain name registration and web hosting service.

One top-level domain name has been reserved for use in documentation as a example. See IETF RFC 2606, Section 2 (https://tools.ietf.org/html/rfc2606).

.example

Three second-level domain names have been reserved for documentation use. See IETF RFC 2606, Section 3 (https://tools.ietf.org/html/rfc2606).

example.comexample.netexample.org

If you go to any of the sites, you see the following message: “This domain is established to be used for illustrative examples in documents. You may use this domain in examples without prior coordination or asking permission.”

Example: The global domain name for all of the NIST time servers:time.nist.gov

Example: time-a.nist.gov 129.6.15.28

Example: time-nw.nist.gov131.107.13.100


http://tf.nist.gov/tf-cgi/servers.cgi

http://tf.nist.gov/tf-cgi/servers.cgi

https://tools.ietf.org/html/rfc2606



Historically, Novell registered the domain name digitalairlines.com. Digital Airlines is a fictitious company invented by Novell for the specific purpose of having a website to use as an example in testing and in documentation. It has been used over the years as an example URL for several Novell products.

Avoid using trademarked names, celebrity names, names of popular fictional characters, and names of public figures in example URLs or domain names.

5.4.13 Users Vary the names used in examples, videos, and images. For a list of approved user names from

regions around the world, see Section 1.42, “User Names,” on page 64. Avoid using real names of people as user names, including employees, family, friends,

celebrities, and public figures. Avoid using proprietary or popular fictional names as user names, including trademarked names,

fictional characters, superheroes, and super villains.

5.4.14 Utilities and Programs Present product, utility, and program names exactly as they were created.

Do not capitalize generic references to types of utilities, such as compiler, linker, and debugger utilities.

When you discuss an application or utility by name, do not use a change of font on the name. When you discuss an application or utility by its file name, use a monospace font and include the

file name extension.

Do not capitalize the word “utility” as part of a utility name unless it is part of your project style sheet.

5.5 Storage ElementsUse good judgment in example names for storage element. Whenever possible, use a meaningful name such as MyWorksheet file or LicenseReport file. Do not use trademarked names or names of celebrities, public figures, and popular fictional characters. Do not use names like Foo, Fu, Foo.bar, and similar as sample file names.

Follow these guidelines for storage elements in documentation procedures and examples:

Section 5.5.1, “Drives,” on page 163 Section 5.5.2, “Discs, CDs, and DVDs,” on page 163 Section 5.5.3, “Disks and Diskettes,” on page 163

CloudAccess iManager MAP

ZENworks eDirectory NLIST

AppManager PlateSpin RConsoleJ

Example: Use the GroupWise Time Stamp utility (gwtmstmp.exe) to ensure that GroupWise user databases include the dates when they were last backed up.


Section 5.5.4, “DOS Devices,” on page 164 Section 5.5.5, “Volumes,” on page 164 Section 5.5.6, “Directories,” on page 164 Section 5.5.7, “Files,” on page 165

5.5.1 Drives When you refer to a specific drive, capitalize the drive letter and include a colon after the drive

letter. Do not capitalize the word “drive.”

When you refer to a NetWare search drive, do not capitalize the words “search drive.”

When you use a drive letter in a path or directory name, do not capitalize the drive letter.

5.5.2 Discs, CDs, and DVDs Use the term “disc” to refer only to a video, audio, or optical disc, not a computer disk or diskette. Use initial capitals and the appropriate tag supplied by your authoring tool.

You can shorten the disc name after you have presented the full name in the discussion.

Refer to the CD by the disc name. Do not use order of appearance to refer to CDs or DVDs.

5.5.3 Disks and Diskettes Use the term “disk” to refer to a computer hard disk or removable disk. The term is also used in

some commonly understood expressions such as “boot disk” or “floppy disk ”or “USB disk”. Do not use “diskette” to refer to a hard disk or removable disk.

Example: Map drive G: to the projects directory.

Example: Map search drive Y: to the sys:login directory.

Example: c:\windows\system32

Example: Use the Personal System/2 Model 50/60 Installation CD provided in your IBM PS/2 package.

Example: The SUSE Linux Installation CD also contains the product documentation.… Insert the Installation CD into drive D: and press Enter.

Wrong: The first CD in your Open Enterprise Server package

Right: The Installation CD in your Open Enterprise Server package

Example: 3.5-inch USB 3.0-compatible external hard drive


When you refer to disks or diskettes by size, use the following forms:

5.5.4 DOS DevicesPresent DOS device names in all capitals without punctuation.

5.5.5 Volumes Present volume names in lowercase unless you are documenting case-sensitive software. If you

are documenting case-sensitive software, present volume names as they appear in the software.

Always put a colon after the volume name, even in running text.

5.5.6 Directories Present directory names in all lowercase unless you are documenting case-sensitive software.

If you are using variables in directory names, use the tags in your authoring tool to present the variable in italics.

Use the appropriate tags to identify directory names in your authoring system. However, do not use any special tags or format changes when directory names are used in headings.

Directory names that are lowercase in running text should use initial capitals in headings, unless they’re lowercase because of case-sensitivity.

When you document case-sensitive software (such as Linux), present directory names exactly as they appear in the software.If you do not know what platform the software will run on, present directory names exactly as they appear in the software.

Example: 3.5-inch diskette

Example: 2.5-inch internal hard drive for notebooks and laptops

Example: 3.5-inch hard drive for laptops and desktops

Examples: LPT1, PRT, COM2

Example: Copy the new version of login.exe into the file server’s sys:login directory.

Example: The public directory is located in main\sys:.

Example: Copy the files into the account\receive\reports directory.

Example: Run software\agents\install.exe where software is your software distribution directory.

Example: Copy the files into the tomcat\webapps\nps\WEB-INF\lib directory.


You can use a forward slash or backslash (as appropriate), or a forward slash or backslash and an ellipsis at the beginning of a directory name if the lowercase presentation might cause confusion. You can also add explanatory text such as “at the root” if you need to be more specific about location.

When a path name can be written with a backslash for some platforms or a forward slash for other platforms, choose one convention and use it consistently throughout the book or documentation set. However, if the documentation becomes platform-specific at any point, such as in command or syntax examples, use the correct syntax for the platform.

Do not use real directory or directory tree names. Doing so creates a high security risk. In addition, avoid using trademarked names, celebrity names, names of popular fictional characters, and names of public figures as example directory names.

5.5.7 Files In general, describe the type of program or file instead of referring to it by its file name extension,

unless a specific extension is a software requirement.

When you use a file name extension in running text, treat it as a file name in a lowercase monospace font and precede it with a period (.xml, .txt), or treat it as an acronym in an uppercase regular font (XML, TXT). When you use the file name extension format, use the article “a” or “an” that applies to the

first letter of the extension, as though the period (or “dot”) is not pronounced.

Do not use an extension acronym as a noun.

Present file names in all lowercase unless you are documenting case-sensitive software. Include the extension in lowercase.

If the file name or a part of the file name is a variable, present the variable in italics.

Example: The \winnt directory is deleted if you enter a different name for the target path.

Example: The path to your \zenworks directory can be different if you use a different volume.

Examples: an applicationa text documenta presentationa worksheetan executable file

Examples: a .com filean .exe file

Wrong: Double-click a BMP to open it in the default editing tool.

Right: Double-click a BMP image to open it in the default editing tool.

Example: Copy the projects.db file into your directory.

Example: the userxxx.db file


Use the appropriate element in your authoring system to identify file names. File names that are lowercase in running text should use initial capitals in headings, unless

they’re lowercase because of case-sensitivity. However, do not use any special tags or format changes when file names are used in headings.

When you document case-sensitive software, type file names exactly as presented in the software.

Use a period to differentiate between a file name and its extension.

You can use the extension by itself (with the period) as a shortcut for references to files of the same type. Alternatively, use the abbreviation of the extension in all caps. Use either option consistently in your doc set.

5.6 Command Line and Prompt In most procedures you should simply refer to the “command line.”

When referring to the prompt, use “command prompt.”

When referring to the interface that displays a command line and prompt, include the word “terminal” in the instructions.

For more information about command line terminology and usage, see Section 3.7, “Command Line Terminology,” on page 123.

5.7 CommandsOur documentation includes both command syntax statements and command examples.

A command syntax statement is a line of text, usually broken out from the running text, that presents a command and any arguments for that command. The command is presented as a literal. The arguments are presented as generic, variable values.

Example: autoexec.bat

Example: Copy all the .txt files to your directory.

Example: Copy all the TXT files to your directory.

Example: On the server command line, enter the following…

Example: The command prompt ends with the pound sign (#), indicating that you are now acting as the root user.

Example: Access a command line by opening a terminal. At the command prompt, type…

Example: Right-click the desktop and select Open Terminal.

Example: Switch to another terminal by using Ctrl+Alt+Fn, where n is the number of an available terminal.


A command example is an instance of a command as it is actually executed, including actual values.

Follow command guidelines when you present command syntax and examples.

Section 5.7.1, “Command Syntax,” on page 167 Section 5.7.2, “Arguments,” on page 168 Section 5.7.3, “Literal Strings,” on page 169 Section 5.7.4, “Long Elements (Multi-line),” on page 169 Section 5.7.5, “Repeated Elements,” on page 170 Section 5.7.6, “Linux and UNIX Commands,” on page 170 Section 5.7.7, “Variables,” on page 170

5.7.1 Command Syntax Present commands in lowercase, unless the software being documented is case sensitive.

The platform is not always indicative of whether the software is case sensitive. For instance, many programs, including DOS and Windows program, require that command line arguments be a certain case. Consider the following example:

The value of the catalina.home parameter (c:\tomcat) reveals that the command is intended to be issued on Windows, which is not case sensitive. However, the java.exe command is case sensitive in evaluating its arguments. Therefore, the -D argument must be uppercase, and the class argument (com.example.HelloWorld) must have the same case as the name of the class file (assumed to be HelloWorld.class in this example).

If you cannot find out whether the software is case sensitive, document the commands as they appear in the software.

Use the tags available in your authoring system to apply a monospace font to a command syntax statement or a command example, but do not use bold in addition to the change of font.

When you refer to commands (whether in running or pulled-out text), present the command in the appropriate case and tag it with the element supplied by your authoring tool.

If the command is too long to fit on a single line, see “Long Elements (Multi-line)” on page 169 for information about the actions you can take.

Example: wcc386 [options] [drive:\path] filename[.ext]

Example: wcc386 d:\accounting\receivables\sofia\reports.doc

Example: java -Dcatalina.home=c:\tomcat com.example.HelloWorld

Example: At the DOS prompt, enter slist.

Example: Use the slist command to...


5.7.2 ArgumentsThe PCWebopedia defines an argument as follows:

“In programming, a value that you pass to a routine. For example, if SQRT is a routine that returns the square root of a value, then SQRT(25) would return the value 5. The value 25 is the argument.”

“Argument is often used synonymously with parameter, although parameter can also mean any value that can be changed. In addition, some programming languages make a distinction between arguments, which are passed in only one direction, and parameters, which can be passed back and forth, but this distinction is by no means universal.”

“An argument can also be an option to a command, in which case it is often called a command line argument.”

“Parameter Names” on page 168 “Required Arguments” on page 168 “Optional Arguments” on page 168 “Mutually Exclusive Arguments” on page 168

Parameter Names Capitalize parameter names as they appear in the code.

Do not use a change of font for parameter names.

Required ArgumentsWhen an argument is required, present it with no brackets or braces.

Optional ArgumentsWhen an argument is optional, enclose it in square brackets ([ ]). This indicates that the user can include the argument or not.

Mutually Exclusive Arguments When an argument is required and there are multiple, mutually exclusive values for the

argument, enclose all values in a single set of braces ( { } ). Use a vertical bar (|) to delimit the individual values.

Example: objectName

Example: sAMAccountName

Example: login username

Example: ftp [-d] [-f]


When an argument is optional and there are multiple, mutually exclusive values for the argument, enclose all values in a single set of brackets ( [ ] ). Use a vertical bar (|) to separate the choices.

5.7.3 Literal StringsEnclose literal strings in straight (typewriter-style) quotation marks (").

5.7.4 Long Elements (Multi-line) When the arguments for a command do not fit on one line, do the following:

Present them as a generic value followed by an ellipsis. List the optional values for each possible argument after the command syntax statement or

command example. Stack the values. Alphabetize all values within each pair of brackets. Place values in uppercase letters before those in lowercase letters. Separate multiple values within a pair of brackets with a vertical bar (|).

Present an argument that has too many possible values to fit on one line by breaking each wrapping line so that it begins with a vertical bar (|).

Example: {0 | 1}

In this example, you must include a value for this argument when you enter the command. You can select 0 or 1 as the value.

Example: [0 | 1]

In this example, you can select 0 or 1 as the value or not include the argument at all.

Example: echo "hello world"

Example: nexm [user] [options…]

Where options can be

[clear | read | stop | write][locate | restore][draw | store | verify | wait][erase | print | reset]

Example: nexm [user] [option]

Where option can be

[clear | draw | erase | locate | print | read | reset | stop | validate | verify| wait | write]


If you use line breaks in printed documentation, place the break after a delimiter (slash, backslash, comma, colon, and so forth), never before.

Remember that when you insert a line break in printed documentation, the line break also appears in online documentation if it is generated from the same source. This can result in unpredictable page appearance for online material.

5.7.5 Repeated ElementsUse an ellipsis (…) to indicate that parameters, options, or settings can be repeated.

5.7.6 Linux and UNIX Commands When referring to a Linux or UNIX command (whether in running or pulled-out text), present the

command exactly as shown (lowercase or uppercase) and tag it with the appropriate tag for your authoring system.

To help distinguish a command from the surrounding text, you can also make specific reference to it as a command.

5.7.7 Variables Variables (substitutable elements) are generic names for arguments that the user must replace

with appropriate values. Use the correct tag to indicate that an element is a variable.

If the variable has more than one word, separate the words with an underscore.

5.8 Parameters In running text, capitalize parameter names as they appear in the code.

Example: ndirsys:\financial\accounting\receivables\mary\reports

Example: login server1\supervisor [option…]

In this command, [option…] represents any number of available options.

Example: Type awk and press Enter.

Example: Do not use the awk command unless you have loaded the latest version of the software.

Example: In the command

ftp -F remote_host

you enter the name of a computer on your network in place of remote_host.


Do not use any additional font change or markup on parameter names.

5.9 Screen Displays and System Responses Format text that represents a screen display or a system response to resemble the text that

appears on the actual screen. The capitalization, symbols, line length, sequence, and so forth, should match what is seen on the screen.

5.10 Software Components in Running TextCommand elements and source code examples often require discussion. This section lists the rules for presenting them in running text.

Section 5.10.1, “Referring to Software Components,” on page 171 Section 5.10.2, “Presenting Literal I/O in Running Text,” on page 171

5.10.1 Referring to Software Components In general, refer to a software component (command, function, utility, system call, or library

routine) by name only.

To refer to a software component in documents for beginners or in an ambiguous context, identify the category of component.

5.10.2 Presenting Literal I/O in Running Text Literal user input or output (I/O) is set off from running text whenever it could be confused with

the text around it. If possible, present the information on a separate line.

Example: objectName

Example: newPassword

Example: The installation has successfully completed. <Press ESCAPE to Continue>

Example: Configure the server by running iManager.

Wrong: Run cat to concatenate files.

Right: Run the cat command to concatenate files.

Wrong: mkdir calls mkdir.

Right: The mkdir command invokes the mkdir system call.


In sentences containing literal I/O, do not confuse sentence punctuation with characters to be typed by the user. If necessary, reword a sentence.

Use the article “a,” not “an,” before the name of a computer element that begins with a period, or dot. This rule applies even when the first letter of the element has a vowel sound. We assume that the word “dot” is voiced.

In procedures, do not use definite articles to modify key names or menu or dialog box options.

5.11 Source FilesA source file is any unprocessed file. Examples include the uncompiled version of a computer program (source code), a data file used as input to a spreadsheet application, or an unformatted SGML document.

Use the tag supplied by your authoring tool to identify source file examples.

Example: To set a path for a program called DAILY, which is in the reports subdirectory of drive G:, add the following line to your file:

set path = "g:\reports\daily"

Confusing: Enter the following command: rm *.

Clearer: Enter rm * to remove all files in the current directory.

Example: NuGet is a .NET program that is compatible with x86/x64 Linux systems with Mono.

Example: TortoiseSVN > Checkout creates a .svn directory in the top-level checkout directory.

Wrong: Click the Appinstaller option.

Right: Click Appinstaller.

Example: #include <stdio.h>main ( ) { char *weekday, *month; int day, year;weekday = "Saturday"; month = "April";day = 18; year = 1990;printf ( "%s, %s, %d, %d/n", weekday, month, day, year ) ; }


Use an ellipsis mark to represent missing portions of a source file. The ellipsis can be horizontal (…) or vertical, as in the following SGML source example:

Example: <CHAPTER LABEL=auto><DOCINFO><TITLE>wksh.pg/386/intro %W% of %G%</TITLE></DOCINFO><SECT1><TITLE>Introduction</TITLE><PARA>This guide is for programmers using the Windowing Korn Shell (WKSH)....<PARA>Computer output such as prompts and messages appear in <LITERAL> computer style type</LITERAL>.Text references to parts of a displayed program or routine also appear in this type style.</PARA></LISTITEM></ITEMIZEDLIST></PARA></SECT2></SECT1></CHAPTER>



6 6Mobile Device Elements

Follow these guidelines for presenting information about computer elements.

Section 6.1, “Mobile App Design and Usability Resources,” on page 175 Section 6.2, “Mobile Apps Documentation,” on page 175 Section 6.3, “Mobile Apps Gesture Terminology,” on page 175

6.1 Mobile App Design and Usability ResourcesConsider these online resources as you work with your teams on usability issues for the mobile app interface.

Apple iOS Human Interface Guidelines (https://developer.apple.com/ios/human-interface-guidelines/overview/design-principles/)

Apple iOS Human Interface Guidelines: Gestures (https://developer.apple.com/ios/human-interface-guidelines/interaction/gestures/)

Apple iOS Developer Resources (https://developer.apple.com/library/content/navigation/#section=Platforms&topic=iOS)

Material Design Touch Gesture Mechanics (https://material.io/guidelines/patterns/gestures.html#gestures-touch-mechanics)

Touch Gestures Reference Guide (https://www.lukew.com/ff/entry.asp?1071)

6.2 Mobile Apps DocumentationFollow these guidelines when you document mobile app interfaces.

Keep interactive elements familiar and predictable. Keep interface text clear and concise. Use relevant and consistent language and imagery in procedures and images. Mobile apps might use touch, gesture, pen, and voice input technologies. Use neutral

terminology that is agnostic to the interactive method used to select options or navigate the interface.

6.3 Mobile Apps Gesture TerminologyA gesture is the motion the user makes to interact with a touchscreen. Use the following guidelines for mobile gesture terminology. We recommend using Apple iOS terminology in Table 6-1, because it is used broadly across various platforms. Table 6-2 shows Android terms that differ in usage from the iOS terminology.

Mobile Device Elements 175

https://developer.apple.com/ios/human-interface-guidelines/overview/design-principles/

https://developer.apple.com/ios/human-interface-guidelines/interaction/gestures/

https://developer.apple.com/library/content/navigation/#section=Platforms&topic=iOS

https://material.io/guidelines/patterns/gestures.html#gestures-touch-mechanics

https://www.lukew.com/ff/entry.asp?1071

Table 6-1 Apple iOS Gesture Terminology

Table 6-2 Android Gesture Terminology

Term Description

drag Moves an element from side-to-side or drags an element across the screen.

flick Scrolls or pans quickly in the direction you want to move the page.

pan Moves an element across the screen at a controlled rate.

pinchpinch inpinch out

Pinch outward to zoom in (enlarge the image).

Pinch inward to zoom out (shrink the image).

press Touch and hold the item.

swipe When performed with one finger, returns the view to the previous screen, reveals the hidden view in a split view controller, reveals the Delete button in a table-view row, or reveals actions in a peek.

When performed with four fingers on an iPad, switches between apps.

tap Activates a control or selects an item.

double-tap Zooms in and centers content or an image, or zooms out if already zoomed in.

touch and hold When performed in editable or selectable text, displays a magnified view for cursor positioning.

When performed in certain views, such as a collection view, enters a mode that allows items to be rearranged.

shake (Shake the device.) Initiates undo or redo.

Term Description

Tap and pull Tap and hold the address bar of the Chrome browser then pull it down to reveal all your open tabs.

Flick Flick left or right to cycle through the open tabs.

Tap and hold Tap an hold the address bar on a Chrome browser, then tap Copy URL to copy the URL to a clipboard.

Swipe Place your finger on the 3-dot menu, then swipe down to open the menu. You can slide to the desired menu option then release.

176 Mobile Device Elements

7 7Cross-References

Cross-referencing information in documentation is a key element in making it usable. This section gives rules concerning references to information within a document, between documents, between sets of documents, or to information on a website.

Section 7.1, “Cross-References,” on page 177 Section 7.2, “Relationship Tables,” on page 178 Section 7.3, “Capitalization of Cross-References,” on page 178 Section 7.4, “Figures and Tables in Cross-References,” on page 178 Section 7.5, “Formatting Cross-References,” on page 179 Section 7.6, “Page Numbers in Cross-References,” on page 179 Section 7.7, “Steps in Cross-References,” on page 180

7.1 Cross-ReferencesIf your authoring tool has an automated cross-referencing capability, use it to create all cross-references.

Follow these guidelines for creating cross-references: When knowledge of one subject helps the reader understand another subject. The

referenced section should add to the user’s knowledge. As pointers indicating where the reader should go next. For example, in a set of procedures

or at the end of a chapter. To describe what type of information readers will find in the section you refer them to.

In a list of all related topics at the end of a section. This list can reduce the number of text references in the section.

When you refer (link) to another manual from your manual, link to that specific manual instead of to the main online documentation website, so users do not need to search for the specific manual you are referring to among the long list of product doc entries. If, for some reason, you cannot link to the specific manual, link to the online doc Table of Contents page for the appropriate release of the product.

Use “about” instead of “on” when you describe the type of information that is available.

Less Descriptive:

See “Setting up HCSS on the Server” on page 31.

More Descriptive:

For more information about HCSS directories, see “Setting Up HCSS on the Server” on page 31.

Example: For more information about user settings, see Section 4.2, “System Preferences,” on page 74.

Cross-References 177

7.2 Relationship TablesIn a topic-based content management system, use a relationship table to establish relationships between topics.

Avoid using inline cross-references to refer a reader to other topics in your Help. Inline cross-references reduce the ability of multiple Help projects to use a single topic.

If you must use an inline cross-reference to refer a reader to a specific topic, use the verb see to introduce the cross-reference.

When you generically reference a book, Help system, or other deliverable, use the verb phrase refer to to introduce the cross-reference.

When you reference a Web site, use the verb visit to introduce the cross-reference.

7.3 Capitalization of Cross-ReferencesFor information about capitalizing cross-references, see “Cross-References” on page 33.

7.4 Figures and Tables in Cross-References Introduce figures and tables before they appear in text. When you refer to a figure or table, a cross-reference is not required if the figure or table comes

immediately before or after the introductory text. In this case, use “the following” or “the preceding” to identify it. Do not use “above,” “below,” “the next page,” “the facing page,” to introduce it.

If you do want to insert a cross-reference to a figure or table immediately preceding or following the reference, use only the figure number and not the page number. If you do insert a cross-reference, do not also add “the preceding” or “the following” to the introductory phrase, as you would in an introductory phrase that doesn’t use a cross-reference to the figure or table number.

Example: For more information about examples and effective ways to introduce them, see Introducing Examples.

Example: For more information about creating a Tempo user account, refer to the Tempo Help.

Example: For more information, visit http://www.compasswatch.com/settings.

Right: The following figure illustrates…

Right: Use the options described in the preceding table to…

Right: Figure 6-2 illustrates…

Wrong: The following Figure 6-2 illustrates…

Right: Use the options described in Table 4-2 to…

Wrong: Use the options described in the preceding Table 4-2 to…

178 Cross-References

When you refer to a figure or table that does not immediately precede or follow the current text, insert a cross-reference that refers to the figure or table by its number and gives the page where it is located.

For a table that doesn’t have a title, create a cross-reference to the nearest heading.

Avoid referring to a figure or table by its title in addition to the figure or table number.

For more information about using and presenting figure and table titles, see “Figure Titles” on page 33 and “Figure Titles to Support Accessibility” on page 212.

For more information about writing introductions to figures and tables, see Section B.2.1, “Introducing Tables and Graphics,” on page 260

7.5 Formatting Cross-References Include all information needed for the user to follow the cross-reference.

An internal cross-reference should refer a reader to a heading and include a page number.

If you cross-reference to a different book, give the heading closest to the destination text and give the book name, but not the full path (that is, no intermediate headings).

If you use a chapter title in a cross-reference, do not use the word “chapter” unless your authoring tool generates it as part of the reference. There are no “chapters” in online documentation, so the word is meaningless in that context.

Avoid enclosing cross-references in parentheses. Cross-references should appear at the end, not in the middle, of a paragraph or sentence.

7.6 Page Numbers in Cross-References Use your authoring tool’s automated cross-referencing feature to insert page numbers. Never

hard-code page numbers. If you refer to documents that are external to the company, do not use page numbers.

Example: Figure 5-1 on Page 10 illustrates…

Example: Use the options described in Table 7-5 on page 50 to…

Example: The table in Section 11.12, “Creating an Email Message,” describes the options…

Example: For more information about setting up a user, see “Configuring a Post Office” on page 25.

Example: For more information, see “Configuring Update Information” in the GroupWise Installation Guide.

Cross-References 179

7.7 Steps in Cross-References Use specific references to steps and include all necessary information for the reader to reach the

referenced information.

Within the same procedure:

Across procedures:

If you must create cross-references manually, capitalize cross-references to specific steps.

Wrong: Repeat the last three steps for each workstation.

Right: Repeat Step 6 through Step 8 for each workstation.

Wrong: Use the name of the driver you selected in the last procedure.

Right: Use the name of the driver you selected in Step 7 on page 35.

Example: Repeat Step 3 through Step 5.

180 Cross-References

8 8Headings

Headings indicate content, clarify organization, and reinforce important concepts for the reader.

Plan headings carefully. They provide a map (table of contents) for the reader. Ensure that the headings reflect a logical flow of information. When users look for information, they generally scan the headings to find it.

Use different heading levels to show the subordination of ideas. Create at least two headings at each level of subordination. A single heading at one level

indicates a problem in the organization of the section and is not consistent with standard outlining procedures. Either eliminate the single heading or add a second heading at the same level.

Make each heading meaningful. Each heading should communicate the most important concept in the related text.

Keep headings in similar sections parallel. Readers should be able to recognize sections with similar kinds of information from the headings. However, do not sacrifice clarity in an effort to make all headings look alike.

Limit the length of headings wherever possible. Lengthy headings cause problems for localization and browser views.

Do not use the telegraphic writing style (omitting articles) to shorten long titles or headings. Rewrite them instead.

Distinguish individual procedural topics from conceptual topics so that users can always expect to encounter a task when they read a gerund construction for the title. Use the gerund form of verbs in most headings for task topics.

Use nouns or short noun phrases in headings for conceptual or reference sections.

Ensure that you include some kind of content in between your chapter or appendix heading and the initial first-level heading in the chapter or appendix. If you do not, the first page of the online document is blank except for the heading.

Section 8.1, “Capitalization of Headings,” on page 182 Section 8.2, “Run-In Headings in Procedures,” on page 182 Section 8.3, “Abbreviations in Headings,” on page 183

Examples: Logging In to the Administration ConsoleChecking in FilesConnecting a Dataset to a Data SourceDesigning a Web Form

Examples: ASP .NET ComponentsDatabaseSource ControlUML

Headings 181

8.1 Capitalization of Headings For information about capitalization in headings, figure titles, and table titles, see “Headings and

Titles” on page 33. For information about capitalization in run-in headings, see “Run-In Headings” on page 37.

8.2 Run-In Headings in ProceduresRun-in headings can be helpful in procedures where you have a long list of fields to be filled in, and you do not want to use a separate step for each field.

Most documentation doesn’t use a bulleted list for this type of material, because it is obvious that the material is a list, and the bullets seem to be redundant. However, if you are listing alternatives that users must evaluate and choose among, it is helpful to use a bulleted list:

You can combine FormalParas with and without bullets to indicate subordination within the list.

Example: 1. Provide the following information:

Login Name: Provide an eDirectory user name that has rights to create eDirectory objects.

Password: Provide the password for the user name.

Tree: Type or select the eDirectory tree where you want to create GroupWise objects.

Context: Provide the full context of the User object associated with the user name you provided.

Example: 1. Select one of the following options:

Inherit Access: Select this option if you want members of this class of service to inherit their access from the default class of service or another class of service that they have membership in.

Allow Access: Select this option to enable members of the class to use WebAccess.

Example: 1. Provide the following information:

Lag time: Specify the number of minutes the system waits to synchronize events to the external database. The default value is 10 minutes.

Schedule: Select when the data is synchronized to the external database:

All the time: Synchronizes events to the external database at regular intervals.

Custom: Synchronizes events at a desired time.

If you select Custom, complete the following fields to set the custom synchronization time:

Day of the Week: Select the day of the week, or select Every day.

Start time: Specify the time to start the synchronization process.

Duration: Specify the synchronization period in minutes.

182 Headings

8.3 Abbreviations in HeadingsDo not spell out a word and give its abbreviation or acronym in parentheses in a heading. Show the abbreviation or acronym parenthetically at the first reference in text.

For more information about using abbreviations and acronyms, see “Abbreviations and Acronyms” on page 18.

Wrong (in heading): Customizing the Graphical User Interface (GUI) for Client Workstations

Right (in following text):

Customizing the Graphical User Interface for Client Workstations

To customize a client workstation’s graphical user interface (GUI) so it reflects a user’s preferences. After customization, the GUI menus, buttons, and pop-ups are…

Headings 183

184 Headings

9 9Graphics

Graphics can illustrate, clarify, explain, demonstrate, and reinforce important concepts for the reader.

Inform your graphics illustrator about your project as early in the documentation project as possible. This prevents any surprises and last-minute-request stress for the illustrator.

Having the illustrator involved from the beginning also benefits your documentation. It lets your illustrator become familiar with your project and needs, it ensures that you have all the necessary graphics in your documentation, and it enables the illustrator to provide the best graphics possible.

Use the following guidelines for designing and including graphics in documentation:

Section 9.1, “Graphics Design,” on page 185 Section 9.2, “Introductions to Figures,” on page 185 Section 9.3, “Callouts,” on page 186 Section 9.4, “Captions,” on page 186 Section 9.5, “Figure Titles,” on page 186 Section 9.6, “Graphics Production Resources,” on page 187 Section 9.7, “Creating Graphics and Screen Captures,” on page 187

9.1 Graphics Design Keep graphics simple. Complex graphics can increase costs and diminish reader

comprehension. Ensure that graphics and text are closely coordinated so that readers can choose which type of

information to look at first. Avoid embedding text in your illustrations. If possible, place all text in callouts, captions, or figure

titles. Graphics with text are difficult to localize. If a graphic shows a sample document, ensure that the text within the sample document is critical to the idea presented; if not, show it as greeked text (gray-bar).

Plan for the text expansion that occurs when the documentation is localized, even though the number of words associated with a graphic might be small. Translated text often expands to more than twice the length of the original English.

Whenever possible, use screen shots of our products, not third-party products. Do not use the real names (first and last), or the phone numbers, extensions, mail stops,

passwords, TCP/IP addresses, URLs, or email addresses of actual employees in your screen shots, scripts, contexts, trees, or other examples. Do not use real server, directory, or tree names. Doing so creates a high security risk.

Do not use a single icon for multiple meanings.

9.2 Introductions to FiguresFor information about writing introductions to figures and tables, see Section B.2.1, “Introducing Tables and Graphics,” on page 260.

Graphics 185

9.3 CalloutsCallouts are text that appear outside a screen shot or illustration. Callout text labels specific portions of the graphic and draws the reader’s attention to them.

Callouts also annotate or explain the usefulness of the illustrated item or feature. They can include information that might otherwise be included in narrative text or procedures.

Callout text should be as brief as possible but should still follow normal syntax rules. Do not omit articles and auxiliary verbs.

Allow enough white space for the text to double in size when translated. When callout text labels an item in a graphic, the callout is a single word or a phrase without

terminal punctuation. When callout text annotates a graphic, the callout is one or more complete sentences ending

with a period. Capitalize the first letter of the first word of a callout and any other words as necessary, such as

product names.

9.4 CaptionsA caption is text that describes a graphic or explains its usefulness to the reader. Captions refer only to a graphic as a whole; they do not label individual parts or details of the graphic.

If you are presenting captions as complete sentences, end them with a period. Present captions below the graphic. If you are presenting captions as sentence fragments, do not use an ending period. Capitalize the first letter of the first word of a caption and any other words as necessary, such as

product names. Do not number captions.

9.5 Figure TitlesThe title refers only to the graphic as a whole; it should not label individual parts or details of the graphic, nor should it give specific instructions to the reader.

Use a figure title on all graphics except inline graphics and graphics in procedures. Place the figure title above the graphic. Use a sentence fragment without a period for a figure title. Capitalize figure titles according to the rules for headings and titles. For more information, see

“Headings and Titles” on page 33. For information about using figure titles for Section 508 compliance, see “Graphics Style for

Accessibility” on page 212. For style guidelines on cross-referencing to figures, see “Figures and Tables in Cross-

References” on page 178.

186 Graphics

9.6 Graphics Production ResourcesImage and icon resources are available to help you design graphics for your documentation projects.

Section 9.6.1, “Brand Central,” on page 187 Section 9.6.2, “Image Gallery,” on page 187

9.6.1 Brand CentralIdentity at Micro Focus Brand Central provides corporate identity resources that you can use to develop illustrations. Resources include logos, product icons, imagery gallery, and color palette.

9.6.2 Image GalleryDoc Production provides the Micro Focus Image Gallery for use by information developers. The gallery is a collection of icons and images that have been developed to illustrate various products. Many are reusable across products, and others can serve as inspiration for your own illustrations. You can search, browse, view, and download high-resolution images and icons from this library. Contact Information Development graphic designer Jayapradeep Narayanan (JP) if you need icons in different sizes than those provided.

9.7 Creating Graphics and Screen CapturesFor information about creating, managing, and naming graphics, see the following guides:

Graphics Guide

Graphics Request Quick Reference

Graphics Review Quick Reference

Graphics Screen Capture Quick Reference

Graphics 187

http://docautobuild.provo.novell.com/image-gallery/

mailto:[email protected]

https://intra.microfocus.net/brandcentral/microfocus/identity.php

http://www.novell.com/documentation/beta/docguides/pdfdoc/graphics_guide/graphics_guide.pdf

http://www.novell.com/documentation/beta/docguides/pdfdoc/graphic_qr/graphics_requests.pdf

http://www.novell.com/documentation/beta/docguides/pdfdoc/graphic_qr/graphics_review.pdf

http://www.novell.com/documentation/beta/docguides/pdfdoc/graphic_qr/screen_capture.pdf

188 Graphics

10 10Lists

Lists contain groups of related items that are considered as a whole, both visually and contextually. Lists are formatted to create order and unity and to enhance the accessibility of the information. If a group of items cannot reasonably be thought of as a unified whole, or if the items need more than a sentence or two of explanation, handle them as a series of sections with headings instead of as a list.

Tables, with or without lines, are also used to organize information, but there are important differences between lists and tables. For information about tables, see “Tables” on page 203.

Section 10.1, “General Rules for Lists,” on page 189 Section 10.2, “Parallelism in Lists,” on page 190 Section 10.3, “Punctuating Introductions to Lists,” on page 190 Section 10.4, “Punctuating List Items,” on page 191 Section 10.5, “Types of Lists,” on page 192

10.1 General Rules for ListsFollow these general rules when you create lists:

A list must consist of at least two items. An introductory sentence is recommended but not required if the heading or paragraph

immediately preceding the list makes a separate sentence unnecessary. For information about punctuating the introduction, see Section 10.3, “Punctuating Introductions to Lists,” on page 190.

When ordering lists, use a chronological, sequential, or logical order wherever possible. If there is no clear order, use alphabetization if you feel it helps readers find what they need. However, remember that lists are not re-sorted in alphabetical order when they are translated.Use word-by-word alphabetization, according to the rules given in Chicago.

Capitalize the first letter of the first word of each item in a list and any other necessary letters. such as product names.

You can use nesting to combine different types of lists. That is, you can include a numbered list as a subordinate level in a bulleted list, or you can include a bulleted list as a subordinate level in a checklist.

Lists 189

10.2 Parallelism in ListsMake all items in a list grammatically parallel. Keep lists as all full sentences or all fragments. Do not mix full sentences with fragments.

For example, to make all items parallel in the following example, re-write the items to begin them all with a verb using the same verb tense.

10.3 Punctuating Introductions to Lists End an introductory sentence to a list with a colon if it is clearly anticipatory of the list, especially

if it contains a phrase such as “as follows,” “the following,” “for example,” or “for instance.” Otherwise, use a period.

If every item in list is a fragment, do not end any of the items with a period. If even one item in a list is a complete sentence, end each item with a period. Do not make the introduction grammatically dependent on the list items for an object or verb. To

many people, an isolated line without punctuation at the end looks like a mistake, and they need to stop and re-read in order to relate it to the list. In addition, this type of construction can cause problems for localization, because languages that do not have the same syntax as English might not be able to break a sentence in the same place.

Wrong: The NetWare 3270 HLLAPI Command Interface performs three functions:

Connects to a presentation space

Disconnecting from a presentation space

A string search in a presentation space

Right: The NetWare 3270 HLLAPI Command Interface performs three functions:

Connects to a presentation space

Disconnects from a presentation space

Searches for a string in a presentation space

Example: To define the effect of double-clicking a name, use one of the following options:

The Transfers File option causes a double-click to transfer the file.

The Launches File option causes a double-click to launch the file.

Contrast with: These options define the effect of double-clicking a name.

The Transfers File option sets a double-click to transfer the file.

The Launches File option sets a double-click to launch the file.

Wrong: This section explains how to

Install networking hardware

Connect workstations to the server

You can install to a local server from

A local network drive

A remote network drive

190 Lists

For more information about writing introductions to lists, see Section B.2.4, “Introducing Lists,” on page 263.

10.4 Punctuating List Items Do not end list items that are incomplete sentences with any punctuation (such as commas,

semicolons, or periods) or with a conjunction.

Watch for individual list items that read like complete imperative sentences but are not actually instructions to the reader. Such items receive no terminal punctuation.

If list items are complete sentences, end each with a period.

If at least one item in the list contains a complete sentence, end all items with a period. A better solution, when possible, is to rewrite the inconsistent item.

Because FormalPara elements need a period or colon after the Title, end each item in a list of FormalPara elements with a period.

Right: This section explains two important concepts:

How to install networking hardware

How to connect workstations to the server

You can install to a local server from either of the following locations:

A local network drive

A remote network drive

Example: This section explains how to do the following:

Install networking hardware

Connect workstations to the server

Example: Use one of the following options for double-clicking a name:

The Transfers File option causes a double-click to transfer the file.

The Launches File option causes a double-click to launch the file.

Wrong: The following virtual machines are supported:

VMware ESX Server 3.5 or later

Xen Virtualization. You must use SUSE Linux Enterprise Server 10 SP2 or later.

Right: The following virtual machines are supported:

VMware ESX Server 3.5 or later.

Xen Virtualization. You must use SUSE Linux Enterprise Server 10 SP2 or later.

Right: The following virtual machines are supported:

VMware ESX Server 3.5 or later

Xen Virtualization on SUSE Linux Enterprise Server 10 SP2 or later

Lists 191

Do not end list items with commas.

10.5 Types of ListsLists fall into four general types, each with a distinctive format:

Section 10.5.1, “Bullet Lists,” on page 192 Section 10.5.2, “Checklists,” on page 193 Section 10.5.3, “Ordered Lists,” on page 194 Section 10.5.4, “Simple Two-Column Lists,” on page 194

10.5.1 Bullet Lists Use an introductory sentence that states the purpose of the list. Typical uses for bullet lists include:

Itemizing parallel elements in a sentence or paragraph. Introducing, summarizing, or providing an overview of information.

Wrong: Select the following options:

Verify ULinks: Checks ULinks to see if they are valid

Report Bad Cross-References Only: Creates a report identifying broken internal cross-references, external cross-references, and ULinks

Right: Select the following options:

Verify ULinks: Checks ULinks to see if they are valid. This option is deselected by default.

Report Bad Cross-References Only: Creates a report identifying broken internal cross-references, external cross-references, and ULinks.

Wrong: The database includes...

Reports,

Forms,

Tables, and

Modules.

Right: The database includes:

Reports

Forms

Tables

Modules

192 Lists

Highlighting pieces of information that would otherwise be buried in a sentence or paragraph.

Bullet List LevelsYou can use multiple levels in a bullet list.

Bullet Lists in Chapter Summaries Use a bullet list to preview or summarize the topics in a chapter or section. List the items in the order in which the topics appear in the part, chapter, or section. Some authoring tools automatically generate a SubToc that creates cross-reference links to the

next lower level of sections.

Bullet Lists in Task OverviewsYou can also use a bullet list to provide an overview of tasks.

10.5.2 Checklists Use a checklist to help the reader gather information or mark items completed in a list of tasks. A

checklist can contain multiple-choice or fill-in-the-blank questions. If you use a list format for software and hardware prerequisites, use a checklist. Organize the information in checklists sequentially, by topic, or by type of question.

OK: You must define a logical unit (LU) and a physical unit (PU) for each SNA Links router location.

Better: For each SNA Links router location, you must define two items.

A logical unit (LU)

A physical unit (PU)

Example: You need the following information for each host session:

The communication service name

The resource type:

Public

Pooled

Dedicated

Example: To install the software, perform the following tasks:

Define all required workstation types

Create a profile for each type

Run the startup program from each workstation

Start the BOOTP service

Lists 193

10.5.3 Ordered Lists Use a numbered list when items have a strict order or hierarchy. If order is not important, use a

bullet list or checklist. Do not use the numbered list element to present a procedure that the user is to perform. Instead,

use the procedure element. For instructions on writing procedures see Chapter 11, “Procedures,” on page 195.

Use a numbered list to present a procedure that the computer performs.

Each list item in an ordered list or task must be a complete sentence that ends with a period.

10.5.4 Simple Two-Column Lists Use a simple two-column list when a long list needs to be formatted to save space. Use a simple list when information can be presented in two columns, with list items in the left

column and explanatory text in the right column.This type of list is similar to a table but has no column labels or headings. The relationship between the list items, and between the information in the two columns, must be self-evident.

Use the styles and tags included in your authoring tool to prepare two-column lists. Make column items parallel or similar in structure. Ensure that columns are wide enough to accommodate translation into languages with long

words. Narrow columns result in poor line breaks or excessive hyphenation. For more information, see “Text Expansion” on page 58.

Try to limit the length of explanatory information (ideally, no longer than 30 to 35 words).

Example: The SNACP and the emulator use the SESSION_STATUS function in the following sequence:

1. The SNACP sends a CONNECT message.

2. The emulator sends a CONNECT acknowledgment.

3. The SNACP sends a SET_PRES_RULES message.

4. The emulator acknowledges SET_PRES_RULES positively.

Example: The domain name must be one word. Do not use any of the following invalid characters:

Space Use an underscore (_) instead

ASCII characters 0-13

@ “At” sign

{ } Braces

194 Lists

11 11Procedures

Follow these guidelines as you document the step-by-step procedures that a user performs in an application.

Section 11.1, “When to Use Procedures,” on page 195 Section 11.2, “Understanding the Procedure Format,” on page 195 Section 11.3, “Procedures Style,” on page 196 Section 11.4, “Run-in Headings in Procedures,” on page 202 Section 11.5, “Verbs for Use in Procedures,” on page 202

11.1 When to Use ProceduresA procedure is a series of numbered steps that explains how to perform a task.

Use the procedure format only for the steps a reader must follow to perform a task. Do not use the procedure format to identify actions that the software or computer performs. Use

a numbered list instead.

11.2 Understanding the Procedure FormatA procedure has a special format to distinguish it from a numbered list, including the following:

An introductory phrase where appropriate.

For a longer discussion of introductions to procedures, including examples, see Section B.2.2, “Introducing Procedures,” on page 262.

The introductory phrase appears in bold text. Formatting elements to distinguish numbered items (steps). Substeps, where appropriate. Markup of field labels, buttons, and section subheadings in the dialog box. Explanatory information, where needed.

For example:

To configure the ARAS for loading:

1 Click Configure Service for Loading, then click ARAS.2 Select a frame type:

Ethernet_SNAP for EtherTalk 2.0 networks Ethernet_II for EtherTalk 1.0 networks

3 Specify the network numbers and AppleTalk zone names:3a Select Loading Service Parameters and press Enter.3b Specify the starting and ending numbers of the network number range.

Procedures 195

The difference between the two integers must be between 1 and 10.3c Specify the AppleTalk zone names.

A valid zone name consists of up to 32 characters that can include letters, numbers, underscores (_), hyphens (-), and spaces.

4 Press Esc twice to save the configuration information and return to the Configure Service for Loading menu.

11.3 Procedures StyleTake advantage of the elements of the procedure format to present procedures that are clear and easy to follow.

Section 11.3.1, “Explain the Purpose,” on page 196 Section 11.3.2, “Keep Procedures Short,” on page 197 Section 11.3.3, “Make Steps Brief,” on page 197 Section 11.3.4, “Combine Multiple Actions,” on page 197 Section 11.3.5, “Distinguish between an Action and a Result,” on page 198 Section 11.3.6, “Use Substeps,” on page 199 Section 11.3.7, “Identify Choices or Alternatives,” on page 199 Section 11.3.8, “Simplify Long Procedures,” on page 200

11.3.1 Explain the Purpose Before you outline the steps, briefly explain why the reader should complete the procedure.

Tell readers what they can do, why they would want to, and what implications their actions might have. Then tell them how. This helps both translators and readers understand what you are describing.

Where appropriate, you can use an introductory phrase immediately before a set of steps. Use a sentence fragment ending with a colon.

An introductory phrase is not required, but it can be used as transition between the explanatory text and the actual steps. Avoid repeating information already given in a heading.For a longer discussion of introductions to procedures, including examples, see Section B.2.2, “Introducing Procedures,” on page 262.

Right: To update the GroupWise client:

Wrong: To update the GroupWise client

Wrong: To update the GroupWise client,

Wrong: To update the GroupWise client, complete the following steps:

196 Procedures

11.3.2 Keep Procedures ShortAvoid writing lengthy procedures that extend for several pages. Procedures that are easy to follow generally contain fewer than 10 steps.

A longer procedure can be restructured by condensing similar actions (see “Combine Multiple Actions” on page 197) and by breaking it down into a series of smaller procedures (see “Simplify Long Procedures” on page 200).

11.3.3 Make Steps Brief Include only the action the reader must perform in the numbered part of a step. Express the

action as a direct imperative. Place any additional information in the explanation that follows the numbered part of a step.

11.3.4 Combine Multiple ActionsYou can combine multiple actions into one step if several actions are part of a single process for the user. For instance, you might want to use several actions in one step to get users from one place to another in the interface or to describe what they do within one dialog box.

Combine multiple actions only if they are obviously related. Do not combine steps just to reduce the number of step numbers in a procedure. Consider usability and readability when combining actions.

Steps with combined actions should be brief. If you have more than two lines in a single step, consider dividing that step into two steps.

In the following procedure, Step 1 gives an example of combining a series of actions in single step. The right-caret separates the actions.

1 In ConsoleOne, click Tools > Licensing Services > Add Licenses.2 Click License File, then click OK.3 Select a license file.4 Select a context for the license certificate, click Add Licenses, then click Close.5 Make a server assignment for each license certificate that you added:

5a Double-click the license certificate, click Assign Server, then select a server.Repeat this step for each new server assignment you want to make.

5b When you have made all the server assignments, click OK.

Confusing: 1. Ensure that all the servers you want to poll have been configured through the CSCON utility as end point servers with one common server specified as the collection point server.

Clearer: 1. Configure all the servers you want to poll as end point servers.

All servers must be configured with the CSCON utility. One common server must be specified as the collection point server.

Procedures 197

Using the Separator Symbol for Menu Items and Dialog Box Tabs When you combine several actions in a step, use the separator symbol (>) to separate menu

items or tabs in a dialog box, but not for other actions you perform within a dialog box or property page.

When describing actions that a user takes within a dialog box or property page, use a series separated by commas. Use “then” as the transition into the last item of the series.

For additional information, see Section B.7.2, “Using “Then” in Procedures,” on page 269. You can use separate steps, or you can combine both kinds of navigation in one step:

11.3.5 Distinguish between an Action and a ResultAvoid formatting the result of a step as another step. Instead, include the result of a step in its explanation; or, eliminate explanatory text if the interface provides adequate explanation.

Right: 1 Click File > New > Mail. [The separator substitutes for the verb in telling users how to navigate the menu system.]

Wrong: 1 Click File > click New > click Mail. [Do not use both verbs and separators in telling users how to navigate the menu system.]

Wrong: 1 Click File, click New, then click Mail. [Use the separator instead of commas to separate actions when navigating the menu system.]

Right: 1 Provide your user name and password, select a server from the drop-down list, specify a tree, then click OK.

Wrong: 1 Provide your user name and password > select a server from the drop-down list > specify a tree > click OK. [Do not use separators to navigate among dialog box options.]

Right: 1 Type the user’s name on the To line.

2 Type a message in the Message box.

Right: 1 Type the user’s name on the To line, then type a message in the Message box.

Wrong: 1 Type the user’s name on the To line > type a message in the Message box.

Right: 1 Select the User object.

2 Click File > Properties > General > Identification.

Right: 1 Select the User object, then click File > Properties > General > Identification.

Wrong: 1 Select the User object > click File > Properties > General > Identification. [The separator between “Select the User object” and “click File” is incorrectly used.]

Wrong: 1. Select the Directory path field in Step 1 on the installation program opening screen and press Enter.

2. A blinking cursor appears at the end of the path statement in the field.

3. Edit the field for your specific target directory and press Enter.

4. The path must include the directory root.

198 Procedures

11.3.6 Use Substeps Use substeps to break a complex step into its component actions. For example:

If a step is long or too complex, format it as a separate procedure. For an example of this, see “Simplify Long Procedures” on page 200.

11.3.7 Identify Choices or AlternativesIf you identify the choices available at a decision point in a procedure, you can present the choices in a bulleted list under the step. For example:

1 Select an installation option: To install NetWare for LAT on the NetWare server you are logged in to, select Install on This

Server. To install NetWare for LAT on a NetWare server other than the one you are logged in to,

select Install on Another Server. To terminate the installation, select Do Not Install This Product.

Another option is to present the choices in a table. For example:

1 Ensure that the device driver is configured to access the new controller.

Right: 1. Select the Directory path field in Step 1 on the installation program opening screen, then press Enter.

A blinking cursor appears at the end of the path statement in the field.

2. Edit the field for your specific target directory, then press Enter.

The path must include the directory root.

Confusing: 1. If you are installing from the hard disk, create subdirectories on the server hard disk to copy the NetWare Connect files.

You must map a drive to the directory you created and copy the NetWare Connect software.

Clearer: 1. Install the NetWare Connect software from the hard disk:

a. Create subdirectories on the server hard disk.

b. Map a drive to the directories you created.

c. Insert the Installation CD.

d. Copy the NetWare Connect software to the directories.

If Then

The device driver for the controller is installed and has been automatically configured

Go to Step 5.

The device driver for the controller is installed but has not been configured

Go to Step 4.

The device driver for the controller has not been installed Go to Step 3.

Procedures 199

You can also use an “or” step when the user has an either-or choice within a set of steps.

1 If you didn’t make changes in the link information, click OK.orIf you changed link information, click the link icon to implement the changes, then click OK.

If choices are conditional, use the following format. “Conditional” means that users must perform an action if certain conditions exist.

1 (Conditional) If Native File Access for UNIX is installed on the NetWare server…

1 (Conditional) For Windows NT, 2000, XP, or 2003 servers and workstations, select when to log in to LDAP, then click Next.

1 (Conditional) If you selected the NMAS client, select one or more NMAS login methods, then click Next.

Ensure that the action is conditional, not simply optional. For instance, the following step is an incorrectly worded optional step.

1 (Conditional) If you want to use…

If choices are optional, use the following format. “Optional” indicates that it is the user’s choice whether or not to perform the step.

1 (Optional) Customize sys:\system\gystart.ncf by adding additional parameters.

1 (Optional) Add a pre-built script to the application list.

Do not use the following formats for optional steps in a procedure:

1 Type a message (optional).

1 If you want, you can mark the rename options.

1 View the Readme file, if desired.

11.3.8 Simplify Long ProceduresThe following example shows how to break up a long procedure into short procedures. This technique is applicable to long procedures with many steps and to complicated procedures with many substeps.

ProblemThe following set of procedures was originally one procedure of 28 steps. That procedure explained how to use the seven fields on a form to configure a range of logical units (LUs). Six of the fields led to one or more lists, entry boxes, or menus that the reader needed to access and operate to complete the form and configure the LU range.

200 Procedures

SolutionThe original procedure was broken into seven smaller procedures, six of which branch from the main procedure (only four are shown in the example).

A list in Step 3 of the rewritten main procedure identifies the purposes and headings of the subordinate procedures. (This list could also have been presented in a table.) The reader returns to Step 3 in the main procedure after completing each subordinate step to finish configuring the LUs.

In this example, the main procedure is identified with a third-level heading and the four subordinate procedures with fourth-level headings. Incorporate your procedure headings into the heading structure of your document.

For brevity, the example shows the main procedure in full, abbreviates the subordinate procedures, and omits the illustrations and the fifth and sixth subordinate procedures.

Configuring a Range of Public LUs [main procedure]You can configure multiple public LUs to have the same attributes.

1 Click Configure SAA Service Profile > Configure Sessions.CSCON displays the Session Configuration menu. If your host link type is SDLC, the downstream PU menu option is not displayed.

2 Click Configure Range of Public LUs.3 Use the Range of Public LUs Configuration form to perform the following tasks:

To enter ranges of LU addresses to identify the sessions you want to configure, see “Identifying an LU Address” on page 73.

To assign VTAM LU names to the LUs, see “Assigning a VTAM LU Name” on page 74. To authorize users to access an LU range, or to remove users from the authorized users list,

see “Authorizing Users” on page 74. To turn certain session attributes on or off, see “Locking and Tracing Sessions” on page 74.

4 When you finish configuring the range of public LUs, press Esc.5 To save the changes, press Enter.

Identifying an LU Address [first subordinate procedure]Identify the range or ranges of sessions you want to configure.

1 In the LU Address field, press Enter.2 …3 …4 To return to the Range of Public LUs Configuration window, press Esc.5 Return to Step 3 on page 201.

Assigning a VTAM LU Name [second subordinate procedure]VTAM LU names are required for all LUs in a type APPC (LU6.2) range. To assign VTAM LU names:

1 In the VTAM/LU Name field, press…2 …3 Return to Step 3 on page 201.

Procedures 201

Authorizing Users [third subordinate procedure]Give a user or group of users access to the pool of sessions you are configuring.

1 In the Authorized Users field, press Enter to…

Locking and Tracing Sessions [fourth subordinate procedure]You can lock a session to prevent use of an LU or to run a trace on the LU. To assign one or both attributes to the session pool:

1 In the Session Attributes field, press Enter to…

11.4 Run-in Headings in ProceduresFor more information about different ways to use run-in headings in procedures, see Section 8.2, “Run-In Headings in Procedures,” on page 182.

11.5 Verbs for Use in ProceduresFor information about common verbs you should use or not use in procedures, along with guidelines, see Section 3.2, “Terminology Spelling and Usage,” on page 77. The following entries are of special interest for procedures:

“choose” on page 85 “click” on page 86 “enter” on page 95 “highlight” on page 97 “in front of / next to” on page 99 “select” on page 107 “specify” on page 108 “type” on page 110

202 Procedures

12 12Tables

Tables list related items and explanatory information that are considered as a whole, both visually and contextually. Tables organize information that is more complex than a simple list of items with one kind of explanatory text. (For more information about using this type of list, see “Simple Two-Column Lists” on page 194.) The table format creates order and unity that enhances the accessibility of the information.

Use the following rules when presenting information in table format:

Use the styles and tags provided by your authoring tool to format tables. State the purpose of the table in introductory text.

If a table immediately follows a heading, avoid repeating information already given in the heading.

Use column labels or headings to indicate the purpose of each column. Use a sentence fragment without a period for the table title. Capitalize row and column labels and table titles as you do headings and titles. For details, see

“Headings and Titles” on page 33. Generally, limit cell content to 30 words or less whenever possible.

Long or complex tables can cause problems for localization and accessibility.

For information about making sure that tables are compliant with Section 508, see “Table Style for Accessibility” on page 213.

12.1 When to Use Table TitlesConsider whether table titles are contributing to the usability and accessibility.

Do the titles help the user locate information?

When a user scans a document, are the titles helpful in understanding the table content, or is the content readily apparent in context, without the title?

Do the titles contribute to the information flow in the document?Titles can function like subheadings in making the information flow apparent to the user. On the other hand, a title might interrupt the information flow if the purpose of the table is obvious in context.

Are the titles redundant with headings or introductory paragraphs?Using similar wording for a heading, a table introduction, and a table title serves only to make the document longer. The table introduction and the table title should add value for the user, not repeat information already given.

Are titles necessary as targets for cross-references?

Tables 203

If you need to cross-reference to a table that doesn’t have a title, there are several workarounds: Cross-reference to the nearest heading. Use the cross-reference options in your authoring tool to cross-reference to the first row of

the table. You must assign an ID attribute value to the row in order for it to appear as a link target option.

If titles are not contributing to usability, doc project teams can choose to have no table titles for some or all documents within a project. You can choose to use table titles in some documents, but not others within a project. For

example, you can choose to not use tables titles within Readmes and Quick Starts. Or you can choose to use tables in one book and to eliminate them in another book.

Ensure that your usage is consistent within a given book. For best practices, see Section 12.2, “Guidelines for Using Table Titles,” on page 204.

12.2 Guidelines for Using Table TitlesIf your project is using table titles in documentation, use the following guidelines:

Capitalize table titles according to the rules for headings and titles. For more information, see “Headings and Titles” on page 33.

Use table titles on most tables, with the following exceptions: Do not use titles on tables within procedures. Do not use titles on single-column tables. The table header row is sufficient, as in the

following example:

Do not use titles on tables used to list simple, repeated syntax examples within reference material.

Return Values:

BASIC GROUPWISE SYSTEM WORKSHEET

Under Item 14: Post Office Language, specify the language for your post office.

NetWare MTA Linux MTA Windows MTA

Syntax: /certfile-[svr\][vol:]\dir\file/certfile-\\svr\vol\dir\file

--certfile-/dir/file /certfile-[drive:]\dir\file/certfile-\\svr\sharename\dir\file

Example: /certfile-\ssl\gw.crt/certfile-server2\sys:\ssl\gw.crt/certfile-\\server2\sys\ssl\gw.crt

--certfile /certs/gw.crt /certfile-\ssl\gw.crt/certfile-m:\ssl\gw.crt/certfile-\\server2\c\ssl\gw.crt

zOK The operation completed successfully.

non-0 An error occurred (see Section 4.1, “Return Values,” on page 117 for a description).

zERR_FILE_NOT_IN_DIO_MODE The file is not in direct file mode.

204 Tables

Do not use titles on worksheets in table format.

Do not use titles on tables in Updates appendixes.

Do not use titles on tables that are used to organize material in a graphical display or in a list format.

Documentation teams can adjust the list of exceptions for a project, but usage must be consistent within a book.

Ensure that you document additional exceptions in your project style guide. Ensure that the exceptions do not create inconsistencies in table numbering for similar tables

within a chapter.For example, it is an obvious inconsistency if there are several similar tables in a chapter, but some have titles and others do not. Or, it might look like information is missing if there are several similar tables in a chapter and the last one is “Table 1.”

Item Example Explanation

1) Tree Name: CORP_TREE Specify the name of the eDirectory tree where your domain and post office will be created.

2) Languages to Install: English-US

German

French

Spanish

Specify the languages to install.

Location Change

“Installing NICI on Windows Servers” on page 449

Added this new configuration section for NICI.

“Understanding External Subscribers” on page 511

In the last bullet, corrected the location for where to find the tednode.properties file:

domain Domain directory

wpcsin MTA input queue directory

0 Live interactive requests

1 Other interactive requests

Arabic Czech Hungarian

Bulgarian German Icelandic

Catalan Greek Indonesian

Tables 205

12.3 Writing Introductions for TablesFor more information about writing introductions to figures and tables, see Section B.2.1, “Introducing Tables and Graphics,” on page 260.

206 Tables

13 13Legal Notice

The Legal Notice provides a copyright statement for the deliverable output and a statement about how to access legal notifications about company software and documentation. Follow these guidelines to prepare a legal notice for Product docs and Help:

Section 13.1, “Legal Notice Style,” on page 207 Section 13.2, “Legal Notice Content,” on page 208

13.1 Legal Notice StyleFollow these style guidelines for the Legal Notice section:

The Legal Department controls the prescribed wording for legal statements and copyright statements that appear in the Product docs and Help.

For information about the current approved wording, see Section 13.2, “Legal Notice Content,” on page 208.

A Legal Notice section appears once in each document. Your authoring tool and publishing process usually automates its location and appearance in the output. During development, place the Legal Notice statement in a location that complies with the

templates in your authoring tool. During publication, the publishing tool should place the Legal Notice appropriately for the

output.

Deliverable Legal Notice Location

Books In PDF output, the Legal Notice appears at the top of the page that follows the cover page.

In HTML output, the Legal Notice is a separate HTML file, with a link that appears at the end of the list in the navigation pane.

Release NotesReadmeQuick Start

For single-file documents, the Legal Notice is the last section in the document in both HTML and PDF output.

Technical Reference In this single-file document, the Legal Notice is the section that follows the introductory abstract.

Help system In an integrated Help system, the Legal Notice is a separate HTML file, with a link that appears at the end of the list in the Help navigation pane.

Help (standalone) If the Help is a collection of standalone pages, the Legal Notice is a separate HTML file, with a Legal Notice link that appears at the foot of each standalone HTML page.

Legal Notice 207

13.2 Legal Notice ContentFollow these content guidelines for the Legal Notice section:

The Legal Notice section includes: A legal statement with a URL to the Legal page of the company website. See “Legal

Statement” on page 208. A copyright statement with the appropriate company name and year of publication. See

“Copyright Statement” on page 208. For Release Notes, the documentation disclaimer statement. See Section 13.2.3,

“Disclaimer Statement for Release Notes,” on page 209. Do not include the following information in the Legal Notice section:

Company address: Company contact information is available on the Contact Us page of the company website. It is not required or desired for an address to appear in the Product docs and Help.

Third-party trademarks statement: A third-party trademarks statement appears on the Legal page of the company website. Instead of repeating it, the Legal Notice provides the URL to the Legal page.

Third-party materials statement: The software package provides a file with information about the copyright and legal notices for any third-party software (including open source software) that is included in a company product. There is an engineering development process for compiling the appropriate information in the Inbound Technology License System (ITLS) and adding it to the product software build. They export a report for a product release and add it to the product build.Information Developers are not responsible for compiling, documenting, or publishing this information. Do not include the file or information in Product docs or Help.

13.2.1 Legal StatementInclude the following statement about various legal information that is required by products and specify the URL to the Micro Focus legal page:

Use this legal statement in the next release where Product docs or Help is rebuilt and republished.

Heritage NetIQ Branded Products

For heritage NetIQ products that still use the NetIQ brand because of government contracts, use the NetIQ Legal page URL instead: https://www.netiq.com/company/legal/. You should use the Micro Focus URL after the NetIQ website implements a redirect to the Micro Focus Legal page, or in the release where your product is rebranded.

13.2.2 Copyright StatementInclude a copyright statement in the following format:


Preferred: Copyright © <current year> <Correct Company Name>. All rights reserved.

208 Legal Notice


https://www.netiq.com/company/legal/

Specify the current year in YYYY format, such as 2017. Use only the year of publication for that release. The software product copyright can include the years of initial release to the current release, such as 2015–2017.

Specify the correct company name as appropriate for products owned by that entity:

13.2.3 Disclaimer Statement for Release NotesIf you provide a Release Notes document separately from the documentation, you must include the following disclaimer statement after the copyright statement. Otherwise, you do not include the disclaimer. For example, add the disclaimer if you include the Release Notes document in the product build or as a download item on the product download page.

NOTE: Do not include the disclaimer for a Release Notes document that you include with product documentation.

13.2.4 Example Legal NoticeThe following is an example of the Legal Notice for all books, single-file documents other than release notes, and release notes documents if the release notes are included with documentation. Ensure that you specify the correct company name in the copyright as appropriate for products owned by that entity.

Acceptable: Copyright © <current year> <Correct Company Name> or its affiliated companies.

Company Name Remarks

Micro Focus Use for Micro Focus branded products where Micro Focus owns the copyrights. Typically, this is used by heritage Micro Focus products and new products.

Micro Focus IP Development Limited

Micro Focus Software Inc. Use for heritage Novell, Inc. products.

Attachmate Corporation, a Micro Focus company Use for heritage Attachmate products.

NetIQ Corporation, a Micro Focus company Use for heritage NetIQ products that have been rebranded as Micro Focus.

NetIQ Corporation Use for heritage NetIQ products that have not been rebranded, such as those with U.S. Government contracts.

The only warranties for this product and any associated updates or services are those that may be described in express warranty statements accompanying the product or in an applicable license agreement you have entered into. Nothing in this document should be construed as creating any warranty for a product, updates, or services. The information contained in this document is subject to change without notice and is provided “AS IS” without any express or implied warranties or conditions. Micro Focus shall not be liable for any technical or other errors or omissions in this document. Please see the product’s applicable end user license agreement for details regarding the license terms and conditions, warranties, and limitations of liability.

Any links to third-party websites take you outside Micro Focus websites, and Micro Focus has no control over and is not responsible for information on third party sites.

Legal Notice 209

The following is an example of the Legal Notice in a Release Notes document that is provided separately from the documentation. Ensure that you specify the correct company name in the copyright as appropriate for products owned by that entity.

Legal Notice



Legal Notice



The only warranties for this product and any associated updates or services are those that may be described in express warranty statements accompanying the product or in an applicable license agreement you have entered into. Nothing in this document should be construed as creating any warranty for a product, updates, or services. The information contained in this document is subject to change without notice and is provided “AS IS” without any express or implied warranties or conditions. Micro Focus shall not be liable for any technical or other errors or omissions in this document. Please see the product’s applicable end user license agreement for details regarding the license terms and conditions, warranties, and limitations of liability.

Any links to third-party websites take you outside Micro Focus websites, and Micro Focus has no control over and is not responsible for information on third party sites.

210 Legal Notice



14 14Accessibility (Section 508)

Section 508 of the Rehabilitation Act sets U.S. government regulations that apply to computer documentation, especially the sections about web-based information.

This section of the Style Guide gives information about what is necessary for our documentation to be compliant with Section 508.

Section 14.1, “Accessibility Style,” on page 211 Section 14.2, “Graphics Style for Accessibility,” on page 212 Section 14.3, “Table Style for Accessibility,” on page 213 Section 14.4, “Publishing Non-Converted HTML,” on page 213

For information about avoiding discriminatory language in writing, see “Discriminatory Language” on page 39.

14.1 Accessibility StyleUse the following guidelines to ensure that your documentation is accessible to a wide range of users, including those with disabilities.

Provide a text equivalent for every non-text element. See “Graphics Style for Accessibility” on page 212 for more information.

Avoid using only visual elements, such a color, to provide information. When you use color, ensure that you also use another method (such as underlining or a font change) to convey the same information.

If possible, avoid creating complex tables. For information about making tables compliant with Section 508, see “Table Style for Accessibility” on page 213.

Discuss features or access methods in terms of their functionality rather than in terms of the individuals or groups who might use them. We often do not know why someone uses a feature. For instance, keyboard shortcuts can be used by someone with a visual disability, but they can also be used by someone who simply dislikes moving back and forth between the mouse and the keyboard. See “People with Disabilities or Illnesses” on page 41 for more information about the appropriate terminology to use.

In procedures, do not attempt to give multiple access paths, such as both mouse actions and keystroke combinations.

If your product has specialized accessibility requirements or features, ensure that they are documented appropriately. For instance, if two software utilities accomplish the same purpose, but one of them is compliant with Section 508 and the other is not, ensure that the information is available.

If your product is exempt from 508 compliance, the help that accompanies the product is also exempt. (An example of this is C-Worthy help for pieces of products that are only used at the server console.) However, exemptions are rare and do not apply to most of our documentation.

Some of our documentation conventions require symbols that might not be voiced correctly in screen readers. Instead of providing a text equivalent for each symbol, we explain them in a documentation conventions section, usually in the Preface of the book.

Accessibility (Section 508) 211

14.2 Graphics Style for AccessibilitySection 508 requires that “a text element for every non-text element shall be provided.” Accordingly, you must have some form of text description associated with screen captures, illustrations, and icons.

To meet this requirement, associate one of the following text equivalents with each non-text element in your document:

Description in running text preceding or following the graphic Figure title Alt text (HTML) Longdesc (HTML)

If your document is part of a larger project, check with the lead writer to ensure that you are consistent with other writers in the project in the way you implement the elements.

For HTML help, complex figures are usually not necessary. Consider profiling the document to exclude the graphic and its description from the document.

Follow these alternative text guidelines for each type of text equivalents.

“Description in Running Text to Support Accessibility” on page 212 “Figure Titles to Support Accessibility” on page 212 “Alt Text (HTML) to Support Accessibility” on page 212 “LongDesc Text (HTML) to Support Accessibility” on page 213

14.2.1 Description in Running Text to Support AccessibilityIf you describe a graphic in running text, you are in compliance with Section 508.

14.2.2 Figure Titles to Support Accessibility Use a sentence fragment without a period for a figure title. Use title capitalization (all words capitalized except articles, prepositions, and conjunctions). For

more information, see “Headings and Titles” on page 33. Figure titles refer only to the graphic as a whole. Titles should not label individual parts or details

of the graphic. Titles should not give specific instructions to the reader. If you use a figure title, you do not need to include Alt text or LongDesc text unless you think the

figure needs more explanation. Avoid redundancy wherever possible.

14.2.3 Alt Text (HTML) to Support Accessibility The text used in Alt text can be a word, phrase or a short sentence. Use sentence capitalization

without end punctuation.

Examples: Figure 1: LDAP Driver FiltersFigure 2: Installation LocationFigure 3: Directory Structure

212 Accessibility (Section 508)

Only text is permitted in a Alt text. If you explain the graphic in the text preceding it, then you should add only minimal information

to the Alt text description. Avoid redundancy wherever possible. If you use a figure title, you do not need to include Alt text unless you think the figure needs more

explanation. Avoid redundancy wherever possible. If you use icons such as Related Topics or Web Links, it is unnecessary to use Alt text to

describe the icon if the icon is accompanied by link text that gives adequate information.

The text description is voiced in a screen reader, and if you move the mouse pointer over the figure in HTML, the text pops up in a yellow balloon. The pop-up text wraps in the Internet Explorer browser, but it might not wrap in other browsers, so the text must be brief.

14.2.4 LongDesc Text (HTML) to Support Accessibility A LongDesc text allows for more information than the Alt text element. Use complete sentences

and sentence capitalization and punctuation. Only text is permitted in a LongDesc text. If you describe the graphic in preceding text, do not repeat the information in a long description.

Instead, briefly identify the graphic using Alt text or a figure title.

The text is voiced in a screen reader, but the text does not pop up when you mouse over the figure.

14.3 Table Style for Accessibility Make your tables as simple as possible. For complex tables, use a table title or provide a description in running text before the table to

explain the basic information in the table. Use title capitalization and a header font change for column header text. If you use row headers (the left column), use title capitalization and a header font change for the

row header text.

14.4 Publishing Non-Converted HTML NOTE: This section applies only to HTML documents posted on heritage TAG documentation websites that do not go through the Doc Production HTML conversion process, for whatever reason.

Examples: Title page illustrationDHCP Settings dialog boxeDirectory tree diagramDisplays the files and folders on your computerGraphic showing the header, three columns, and a footer

Example: This illustration shows the Inventory tree set up with one server that has ZfD3, and another server with ZfD3 SP1. A third server, selected for installing ZfD 3.2, also has ZfD 3.

Example: This illustration shows the Inventory tree set up with one server that has ZfD3, and another server with ZfD3 SP1. A third server, selected for installing ZfD 3.2, has ZfD 3; however, the fourth server, which is also selected for installing ZfD 3.2, does not have ZfD 3.

Accessibility (Section 508) 213

When you mark non-converted HTML documentation, all the documents should look and act alike, so the following code should appear in the <head> portion of each HTML file [as of DocSys 11-10-2017]:

<link rel="stylesheet" href="/documentation/docui_b/docmain.css" />This command ensures that the non-converted HTML doc has the same look-and-feel characteristics (font, link format, and so forth) as our converted HTML doc. For links, the text is underlined and has the possibility of two colors (one pre-clicked and one post-clicked).

214 Accessibility (Section 508)

III IIIStructure

Structure guidelines describe the content templates for documentation deliverables.

Chapter 15, “Reuse,” on page 217 Chapter 16, “Release Notes,” on page 219 Chapter 17, “Videos,” on page 229 Chapter 18, “Glossaries,” on page 235 Chapter 19, “Indexes,” on page 245 Chapter 20, “Help,” on page 249 Chapter 21, “Developer Documentation,” on page 251

Structure 215

216 Structure

15 15Reuse

Write content once and use techniques in your authoring tool to share and reuse it as needed. This strategy decreases the overall topic size and reduces time spent editing, revising, and translating content.

Do not copy and paste paragraphs or sections for reuse. A copy-and-paste strategy creates more work for editing, revision, and translation.

Reuse 217

218 Reuse

16 16Release Notes

Release Notes provide information about new features and enhancements, known issues for the current release, and resolved issues that were reported for the previous release. Use the guidelines in this section to decide what new defects and resolved issues to include and how to present the information in Release Notes.

Section 16.1, “Release Notes Style,” on page 219 Section 16.2, “Release Notes Content,” on page 221 Section 16.3, “Resolved Issues,” on page 225 Section 16.4, “Known Issues,” on page 226 Section 16.5, “Updates and SupportLine,” on page 227 Section 16.6, “Contacting Micro Focus,” on page 228

16.1 Release Notes StyleFollow these style guidelines when you prepare Release Notes and Readmes.

Section 16.1.1, “Deliverable Name and Audience,” on page 219 Section 16.1.2, “Section Numbering,” on page 220 Section 16.1.3, “Cross-Reference Links,” on page 220 Section 16.1.4, “Navigation Links,” on page 220 Section 16.1.5, “Deliverable Formats,” on page 221

16.1.1 Deliverable Name and Audience

NOTE: Other teams, such as Development and Technical Support, might use the term “Readme” for the document they supply with sample programs and field test files. Such documents are not governed by the Style Guide.

For more information about releases, see Section 4.5, “Product Release Types and Version Numbers,” on page 147.

Deliverable Name Release Audience

Release Notes Major releaseMinor releaseService pack release

New customers who are installing for the first time

Existing customers who are installing new instances, reinstalling existing instances, or updating to a new release version.

Readme Patch updateHotfix

Existing customers who are updating the product.

Release Notes 219

16.1.2 Section NumberingDo not apply section numbering in the published output. For book format, only chapter headings and part headings (if used) are numbered.

16.1.3 Cross-Reference Links You can use internal cross-reference links. You can use external cross-references:

Pages on the Micro Focus website or other company websites.

Third-party websites. Ask IT to create a URL redirect that first opens a Micro Focus landing page, then continues to the target website. Verify the cross-reference with each release and request that IT modify the redirect if necessary. Using a redirect enables you to fix a broken cross-reference link to a third-party website without republishing.

16.1.4 Navigation LinksYou can use in-document navigation links.

Your authoring tool and publishing process might automatically generate the navigation pane and links. The SubToc element in the DocSys authoring tool can automatically generate the top-level navigation links in a section.

Examples: Previous Release Notes and ReadmesKB ArticlesChange logsResolved Issues listInstallation instructionsLicense informationSupported platformsSupported applicationsFeature comparison tablesBackwards compatibility information

Example: For more information, see Windows 2000 Server Active Directory - Plan (http://www.microfocus.com/docs/links.asp?eit=win2k_asd) in the Microsoft TechNet Library.

HTML: Navigation paneTop-level navigation linksIn-document navigation links

PDF: Navigation paneIn-document navigation links

220 Release Notes

http://www.microfocus.com/docs/links.asp?eit=win2k_asd

16.1.5 Deliverable FormatsProvide Release Notes in HTML and PDF formats, which are web-friendly and platform independent. HTML output works in any popular web browser.

For most products, this document is a single file published in HTML and PDF format. For complex products, you can use a multi-chapter book format. For online access, you can

publish in any supported online format, such as multi-page HTML, single-page HTML, or PDF format.

If you include Release Notes in a build, publish the document in a standalone HTML file format.

16.2 Release Notes ContentFollow these guidelines when you prepare content for the Release Notes.

Section 16.2.1, “Essential Topics,” on page 221 Section 16.2.2, “Other Possible Topics,” on page 223 Section 16.2.3, “Topics to Exclude,” on page 224

16.2.1 Essential TopicsFollow these guidelines to prepare the following essential information for Release Notes:

Section Headings Priority Description

Header Banner and Title Mandatory The header background is the company-branded header image and appropriate company logo.

Title: ProductName X.X.X.X Release Notes

Example: PlateSpin Protect 11.2.1 Release Notes

Example: Cloud Manager 2.5 Patch 1 Release Notes

Date Mandatory Month Year

Example: April 2017

Version Information Optional Version information for certain components of the product is mandatory if the component displays a version number in the UI that differs from the product version reported in the operating system Control Panel (or similar on non-Windows platforms).

Example: Cloud Manager 2.5 includes Cloud Manager Application Server 2.5 and Cloud Manager Orchestration Server 3.5.

Overview / Product Description / Introduction

Optional for interim releases

For major releases, include a brief product description for the benefit of new customers.

For any release, optionally include a brief overview about the release or a brief introduction to the release.

Release Notes 221

What’s New Mandatory Include a list of new features and improvements, or link to the separate document or help that provides this information.

Do not include resolved issues or behavior and usage changes in this section.

List items in the order of importance, not alphabetically.

(Optional) Include the following paragraph at the beginning of the section. Remember to customize the product feedback information and links, or omit those two sentences.

Many of these improvements were made in direct response to suggestions from our customers. We thank you for your time and valuable input. We hope you continue to help us ensure that our products meet all your needs. You can post feedback in the Sentinel forum (https://forums.microfocus.com/forumdisplay.php/1344-Sentinel) on Micro Focus Forums, our online community that also includes product information, blogs, and links to helpful resources. You can also share your ideas for improving the product in the Ideas Portal (https://ideas.microfocus.com/mfi/sentinel).

Significant Changes in Behavior or Usage

Optional Briefly list changes in the release that might affect the behavior of its existing applications or features.

Briefly describe the change and the application or feature it affects,

If appropriate, add a link to the location of the most relevant procedure or topic that reflects the change.

Some Customer Care departments require this information.

Unsupported or Deprecated Functionality

Optional Provide information about features that have been deprecated, obsoleted, or are no longer supported.

See Section 4.8, “Future Functionality,” on page 149.

Known Issues Optional Provide a list of any severe issues in the current release that might affect the installation or the operation of specific features as well as any late-breaking issues that could not be included in the Product docs. Alternatively, link to the KB Article that lists the issues.

See Section 16.4, “Known Issues,” on page 226.


222 Release Notes

https://forums.microfocus.com/forumdisplay.php/1344-Sentinel

https://forums.microfocus.com/forumdisplay.php/1344-Sentinel

https://ideas.microfocus.com/mfi/sentinel

16.2.2 Other Possible TopicsFollow these guidelines to prepare other possible topics in the Release Notes. If the information is documented in the Product docs, you should link to it instead of repeating the details in the Release Notes.

Resolved Issues Mandatory

(Optional for major releases)

Provide a list of bugs or defects that were resolved in this release. Optionally, provide a link to a document or to a Knowledge Base article where this information is provided.

The section is optional for major releases.

Include the section for minor releases and service packs if there are resolved issues.

The section is mandatory for patch updates and hot-fix updates because resolved issues are the primary focus of those releases.

See Section 16.3, “Resolved Issues,” on page 225.

Installing ProductName Mandatory Provide a minimum set of instructions about the system requirements and how to install the specific release. You can optionally include information about how to obtain the product and minimum set of instructions for update.

Alternatively, link to the installation instructions in the Installation Guide or Product doc.

Licensing Information Optional Include licensing information or licensing instructions that are relevant to the release. Alternatively, link to licensing information in the Installation Guide or Product doc.

Supplementary Information Optional Include late-breaking supplementary information that did not make it into the Product docs before the final product build.

Additions to Documentation Optional Include any documentation updates for new features or enhancements where the Product docs are not updated for interim releases.

Updates and SupportLine Mandatory (COBOL/Borland only)

See Section 16.5, “Updates and SupportLine,” on page 227.

For COBOL/Borland, use this section instead of “Contacting Micro Focus”.

Contacting Micro Focus Mandatory See Section 16.6, “Contacting Micro Focus,” on page 228.

For COBOL/Borland, use “Updates and SupportLine” instead.

Copyright and Disclaimer / Legal Notice

Mandatory Release Notes must include a legal notice statement and copyright statement.

NOTE: If you add other possible topics, make this the final section of the document.

See Chapter 13, “Legal Notice,” on page 207.


Release Notes 223

16.2.3 Topics to ExcludeFollow these guidelines about information to exclude from the Release Notes:

Do not include the following details: The End User’s License Agreement (EULA). Promises about providing fixes or enhancements in the future. See Section 4.8, “Future

Functionality,” on page 149. Do not include sections for the following information:


Supported Software / Tested Software/ Third Party

Optional Provide information about any Third-Party Software that is supported by the product. Alternatively, provide a link to this information in the Product doc or on the Micro Focus website (or the appropriate company website).

End of Support / Planned End of Support

Optional Include information about planned end of support for features, products, or functionality.

See Section 4.8, “Future Functionality,” on page 149.

Modified Files Optional Provide a list of files that are modified by this release. Alternatively, provide a link to the list of modified files in the Product doc or KB Article.

Some products might require this section for a hotfix release.

Backward Compatibility Optional Provide details about backward compatibility with earlier Micro Focus products or earlier versions of the same products. Alternatively, provide a link to the compatibility information in the Product doc.

Previous Releases Optional Provide information about how to locate documentation for earlier releases or their release notes.

Section to Exclude Remarks

Obtaining the Product / Update Do not include as a separate topic. Include this information under the Installing ProductName section.

Tell Us What You Think / Send Us Feedback

Reserve sections like this for the Help or online documentation.

Last Reviewed / Applies To / Summary If this information is necessary, include it in the Overview / Product Description / Introduction section.

Feature Comparison If this information is necessary, add it to the Product doc or on the company website, then link to it from the Overview / Product Description / Introduction section.

For example, this might be a comparison of the different editions of a product, such as Enterprise, Professional, and Standard.

Other Resources Reserve information like this for the Product doc.

Supported Platforms Use Supported Software / Tested Software/ Third Party instead.

224 Release Notes

16.3 Resolved IssuesCustomers and partners want to know the disposition of defects that they reported for the previous release. For this purpose, the Resolved Issues section of the Release Notes includes information about fixes for issues from the previous releases that the PM wants to make public: Known issues: Move the issue from Known Issues to Resolved Issues. Summarize the issue

and replace the workaround with the fix. Customer or partner issues: Include issues reported by customers and partners that are likely

to have been encountered by others. Exclude issues with limited likelihood or impact. Noteworthy issues: Include issues where the fix requires any of the following, regardless of

who reported it: Special handling or a one-time procedure in order to implement it A link to a TID (Technical Information Document) or article in the Knowledge Base Information about the related new or changed UI or behavior, with a link to documentation

as needed “Hot” issues (as determined by the PM and Dev Team) that are particularly important to

customers or partners

If the release has a small number of resolved issues, provide a description of each one. See “Issue and Fix Descriptions” on page 225.

If your release has a large number of software fixes, publish a Resolved Issues List for the release and link to it from the Resolved Issues section. In addition, include descriptions for the few noteworthy issues. See “Resolved Issues List” on page 226 and “Issue and Fix Descriptions” on page 225.

16.3.1 Issue and Fix DescriptionsFor a software fix, briefly describe the defect and provide information about how the issue was resolved. Include the associated defect number from the defect-tracking system with the description, as described for Known Issues. If it is needed, provide information about special handling or procedures required to implement the fix, link to a TID, or link to where it is documented.

Where the title and description are not repetitive, use the following format:

Where the title and description are repetitive, use the following format:

Summary Heading for the Defect that Helps the Reader Recognize the Problem

Issue: Briefly describe the issue. (Bug xxxxxx)

Fix: Briefly describe the fix. Include additional information as needed.


Briefly describe the resolution. (Bug xxxxxx)

Include additional information as needed.

Release Notes 225

16.3.2 Resolved Issues ListWork with the PM and Engineering to compile a list of defects. For each defect, provide the defect number and a meaningful title. Organize defects by component or feature to make it easier to find issues of interest. See the following examples:

For Filr, engineering compiles the list. Documentation publishes it in PDF format on the doc website for the release, but does not list it on the doc TOC. It is available only through the link in the Release Notes. See Filr 2.0 Bug Fixes (https://www.novell.com/documentation/novell-filr-2/filr-2-relnote/data/filr-2-relnote.html) in the Filr 2.0 Release Notes.

For ZENworks, engineering compiles the list and Customer Care publishes it as a TID in the Knowledge Base. See Issues Resolved in Version 11.4.2 (https://www.novell.com/documentation/zenworks114/readme_zenworks1142/data/readme_zenworks1142.html#b1ctvz0h) in the System Update (2.4.2) for ZENworks 11.SP4 Readme.

16.4 Known IssuesCustomers and partners want to know about defects in the release that they might encounter and how to avoid, mitigate, or work around them. For this purpose, the Known Issues section of the Release Notes includes information about defects in the current release that your team wants to make public. Known issues are per-release and version-specific. Include only defects that were introduced by

the release. Work with the PM and Development Team to determine candidate issues for the release notes.

Include severe defects that users are likely to encounter or have a significant impact. Exclude issues with limited likelihood or impact.

Exclude issues that might reveal potential security vulnerabilities to hackers. Your team should resolve such security-related defects as soon as possible and release the fix in a patch or hotfix.

Include any late-breaking issues that could not be included in the Product docs. Refer customers to the relevant section in the Product docs where longstanding unresolved

issues are documented, such as Troubleshooting. Review the list of known issues from the previous release:

Move “fixed” issues to Resolved Issues. See Section 16.3, “Resolved Issues,” on page 225. Assess each “won’t fix” and “open” issue to determine whether it impacts the current

release. Consider whether it should be moved to documentation. Different departments have their own process for handling these issues. For example, you might create a troubleshooting topic, add it to the Product doc, create a KB article, or do nothing.

If you resolve a “won’t fix” or “open” issue with documentation, move the issue to Resolved Issues and link to the relevant doc or KB Article.

For a major release, work with your Development Team to review any unresolved known issues for defects in the previous major release and interim releases that still occur in the current release. Resolve them through documentation in Product docs or KB Articles, or bring them forward as appropriate.

226 Release Notes

https://www.novell.com/documentation/novell-filr-2/filr-2-relnote/data/filr-2-relnote.html

https://www.novell.com/documentation/zenworks114/readme_zenworks1142/data/readme_zenworks1142.html#b1ctvz0h

16.4.1 Defect NumbersOptionally include the associated defect number from the defect-tracking system with the description:

Display the defect number in parenthesis at the end of the description. If your authoring tool offers a standard way to present the information, track and display the

defect number consistently as appropriate for the tool. If you do not display the defect numbers, track them as a Remark (hidden) for each issue.

The defect number should reflect the source defect-tracking system. If multiple defects apply to the same issue, list them as shown:

16.4.2 Issue and Workaround DescriptionsFor a known issue, briefly describe the defect and provide information about how to avoid, mitigate, or work around the issue.

If the issue has a workaround, use the following format:

If the issue does not need a workaround and causes no harm, use the following format:

16.5 Updates and SupportLineFor COBOL/Borland only, use this section heading and content instead of “Contacting Micro Focus”.

Include the following information:

A link to Micro Focus SupportLine if your Release Notes document is not uploaded to SupportLine in HTML format:

Defect-Tracking System Single Defect Multiple Defects

TeamTrack (ENG123456)(DOC123456)

(ENG123456, ENG789101)(DOC123456, DOC789101)

Bugzilla (Bug 123456) (Bugs 123456, 789101)

Service Requests (SR 123456789101) (SRs 123456789101, 234567891011)


Issue: Briefly describe the issue. If it is appropriate, include error conditions or symptoms. (ENG123456)

Workaround: Briefly describe how to avoid, mitigate, or work around the issue. If no workaround is needed, state why the issue is benign and can safely be ignored.


Briefly describe the issue. State why the issue is benign and can safely be ignored. (Bug 123456)

For product support, visit Micro Focus SupportLine (https://www.microfocus.com/support-and-services/contact-support/), then select the appropriate product category.

Release Notes 227

https://www.microfocus.com/support-and-services/contact-support/

Information about what details to send to SupportLine when an issue occurs. Information about product updates and additional resources.

See Examples on the Micro Focus Intranet for the prescribed wording.

16.6 Contacting Micro FocusUse the following prescribed heading and wording for this Sect1-level topic in the Release Notes.

NOTE: For COBOL/Borland, see Section 16.5, “Updates and SupportLine,” on page 227.

Contacting Micro Focus

For specific product issues, contact Micro Focus Support at https://www.microfocus.com/support-and-services/.

Additional technical information or advice is available from several sources:

Product documentation, Knowledge Base articles, and videos: https://www.microfocus.com/support-and-services/

The Micro Focus Community pages: https://www.microfocus.com/communities/

228 Release Notes

http://intranet.microfocus.com/dept/WorkSpaces/UserInformation/Authoring/Forms/AllItems.aspx?RootFolder=%2Fdept%2FWorkSpaces%2FUserInformation%2FAuthoring%2FDevelopment%20of%20Standards%2FStandardized%20Release%20Notes%2FExamples&&InitialTabId=Ribbon%2EDocument&VisibilityContext=WSSTabPersistence

https://www.microfocus.com/support-and-services/




https://www.microfocus.com/communities/

17 17Videos

Video tutorials and demonstrations are an integral part of product documentation. A video provides information that complements and supplements, but does not replace, the written documentation. A video can help customers become familiar with targeted features of our products and implement them into their environments more quickly and effectively than they might have done otherwise. Videos can help users become familiar with new features, understand the difference between old functionality and new functionality, see how to accomplish a complex task, and so forth.

Follow these guidelines to produce videos about your product. Many resources are available to help you product a quality video.

Section 17.1, “Video Production Resources,” on page 229 Section 17.2, “Branding,” on page 229 Section 17.3, “Presentation Template and Icons,” on page 230 Section 17.4, “Video Recording,” on page 230 Section 17.5, “Voiceover Recording,” on page 230 Section 17.6, “Video Editing and Post-Production Services,” on page 231 Section 17.7, “Video Publication on YouTube,” on page 231 Section 17.8, “Video Links in Documentation,” on page 233

17.1 Video Production ResourcesThe Information Development Videos SharePoint on the Micro Focus Intranet (../WorkSpaces/Information Development/Vision-Design/Videos/) provides helpful video items to use when you create product training videos:

Music Sound effects Video script template Video production workflow diagrams List of available high-quality recording microphones at your site

17.2 BrandingVideos should reflect corporate branding. Use official corporate logos, colors, typefaces, icons, and imagery to help ensure that our videos represent the corporate identity. You can download these resources from Identity at Micro Focus Brand Central. Follow the guidelines for their use as you develop illustrations for your video.

Follow the additional guidelines for video production at Video at Micro Focus Brand Central (https://intra.microfocus.net/brandcentral/microfocus/templates.php#video). You can download corporate and training video intros, end screens, and other resources to use when you create videos.

Videos 229

http://intranet.microfocus.com/dept/WorkSpaces/UserInformation/VisionDesignArchitecture/Videos

http://intranet.microfocus.com/dept/WorkSpaces/UserInformation/VisionDesignArchitecture/Videos

https://intra.microfocus.net/brandcentral/microfocus/templates.php#video

https://intra.microfocus.net/brandcentral/microfocus/identity.php

17.3 Presentation Template and IconsUse the 16:9 aspect ratio presentation template and icons from the PowerPoint Presentation Template at Micro Focus Brand Central to create title slides and information slides for your video presentation.

Export your slides as high resolution PNG files instead of recording them. An export bitmap resolution value of 200 provides a widescreen pixel resolution of 2667p x 1500p, which is higher quality than the 1080p and 720p video resolution and should easily down-convert.

For information about how to set up PowerPoint to use a default export resolution with a decimal value of 200, see the Microsoft Help article: How to Change the Export Resolution of a PowerPoint Slide.

17.4 Video RecordingCamtasia is the preferred recording and editing application to produce videos. Record your video in a 16:9 widescreen aspect ratio at a minimum resolution of 1280 x 720.

When you produce and share your video from Camtasia, use the following settings:

17.5 Voiceover RecordingAudacity (http://www.audacityteam.org/) is a freeware audio recording and editing application that is the preferred method to use when you create voiceovers.

Use headphones for better sound clarity and precision when you record and edit audio.

A high-quality Blue Yeti HQ USB microphone is available for Information Developers to use in most Micro Focus offices. See the Micro Focus Office Mic List (../WorkSpaces/Information Development/Vision-Design/Videos/Documents and Guides/Micro Focus Office Mic List.xlsx)

Parameter Recommended Setting

Custom Production > File format MP4

Custom tab > Produce with controller Disabled

Size tab > Keep aspect ratio Enabled

Size tab > Width 1280

Size tab > Height 720

Video Settings tab > Frame rate 30

Video Settings tab > Keyframe every 5 seconds

Video Settings tab > H.264 profile High

Video Settings tab > H.264 level Auto

Video Settings tab > Encoding mode Quality at 75%

Audio Settings tab > Encode audio Enabled

Audio Settings tab > Bit rate 512 kbps

230 Videos

https://intra.microfocus.net/brandcentral/microfocus/templates.php#presentation

https://intra.microfocus.net/brandcentral/microfocus/templates.php#presentation

https://support.microsoft.com/en-us/help/827745/how-to-change-the-export-resolution-of-a-powerpoint-slide

https://support.microsoft.com/en-us/help/827745/how-to-change-the-export-resolution-of-a-powerpoint-slide

http://www.audacityteam.org/

http://intranet.microfocus.com/dept/WorkSpaces/UserInformation/_layouts/xlviewer.aspx?id=/dept/WorkSpaces/UserInformation/VisionDesignArchitecture/Videos/Documents%20and%20Guides/Micro%20Focus%20Office%20Mic%20List.xlsx

For recording tips from Corporate Videographer Russ Dastrup, see the Blue Yeti Microphone Tips video on the Micro Focus Support and Training channel on YouTube.

http://www.youtube.com/watch?v=Gl0htPMgFiM

17.6 Video Editing and Post-Production Services If you need help with video requests or are having troubles with any video work, please contact Greg Posten and James Aguilar. After you produce the video, you can request a video review.

In a post-production review and edit, the Micro Focus video team can correct video and voice issues directly in the video project. They will add required information for publishing, and then export the project as a final video. To facilitate this work, you should submit your full Camtasia project for review and edit rather than the actual published video.

To submit your video project for review:

1 Export your project from Camtasia. Open your Camtasia project, then select File > Export project as zip.

2 Upload the zipped project files to secure location, such as a shared folder in your corporate Micro Focus Filr account (https://filr.attachmategroup.com). Log in with your corporate user name and password, then share the folder with your Video Team contact.

3 Send the following information to your Video Team contact via email: A sample video title. A short video description, including the product version number. A target URL to send viewers to for more information. This is usually the Product, Feature,

or Event page. A comma-separated list of keywords to use for search engine optimization.

17.7 Video Publication on YouTubeInformation Development videos are published by Micro Focus Marketing on the Micro Focus Support and Training channel on YouTube. The Marketing tem will post it on YouTube and add it to the appropriate playlist in the Product Portfolio channel. You can Subscribe to the channel to get notifications about new videos.

To have a video posted on YouTube, you must create a request using the Micro Focus portal for WorkFront (https://microfocus.my.workfront.com). All Micro Focus Global ID Team members as of May 2018 should have a WorkFront account. If you do not have WorkFront account, send an email to Steve Dame in Micro Focus Marketing to request one. Allow at least 2 business days to receive WorkFront access information. Your WorkFront login credentials are your corporate email address and a password for WorkFront. WorkFront does not use your corporate login credentials.

To submit a video production request:

1 Log in to the Micro Focus portal for WorkFront (https://microfocus.my.workfront.com) by using your WorkFront account credentials.

2 In WorkFront, click New Request, then select Marketing Services Request as the request type.3 In the Marketing Services Request menu, select the primary Product Group for your request:

ADM (Application Delivery Management)

Videos 231

https://www.youtube.com/channel/UCZHLAuzLykBK09uEJesc2og

https://www.youtube.com/channel/UCZHLAuzLykBK09uEJesc2og

https://www.youtube.com/channel/UCZHLAuzLykBK09uEJesc2og?sub_confirmation=1


https://www.youtube.com/watch?v=Gl0htPMgFiM






http://www.youtube.com/watch?v=Gl0htPMgFiM

https://microfocus.my.workfront.com




https://filr.attachmategroup.com

AMC (Application Modernization & Connectivity) IMG (Information Management & Governance) ITOM (IT Operations Management) Other Security SUSE Vertica

4 From the Product Group menu, select Creative/Design as the type of work for the request.5 From the Work Type menu, select Video Publishing.6 In the Video Publishing request form, complete Video Publishing request information.

7 Add the video documents you want to publish and wait until the document upload is complete before you continue. Alternatively, provide a link under Additional Instructions to a shared folder location where you have made the files available for download by the Marketing Services representative.For example: Video file in MP4 format (if the video file is complete with video bookends and YouTube

information that has been added by your Video Team contact) Exported Camtasia project files (Open your Camtasia project, then select File > Export

project as zip.) A file that contains your context information for the video:

A sample video title. A short video description, including the product version number.

232 Videos

A target URL to send viewers to for more information. This is usually the Product, Feature, or Event page.

A comma-separated list of keywords to use for search engine optimization. 8 Click Submit Request. 9 WorkFront sends an automated email acknowledgment for your request.

10 A Marketing Services Project Manager will contact you by email within 2 business days to discuss the request and provide an estimated work completion time.

11 A Marketing Services Project Manager will contact you again when the request is completed and ready for review.

12 Notify your stakeholders that the video is available and provide a link to the newly published video.

17.8 Video Links in DocumentationDocumentation should reference the video for viewing on the Micro Focus Support and Training channel on YouTube. Do not embed video files in your document’s PDFs or HTML files. Videos are not hosted on our Documentation websites.

Direct links to the published video can become problematic over time because YouTube assigns a new unique video ID each time you update the video. Create an online HTML page for video links that is easily modified but that provides a static target for video links in your documentation. For example, you can use a single-page document template to list the videos with their YouTube links.

Linking to a static URL instead of a YouTube URL ensures the following benefits:

Users always access the most recent and correct version of the video. Video links in the online documentation and help files are never broken. You can update videos without republishing documentation or help files.

You can use direct links to videos in the Video Tutorials section of the online TOC page for the product release. Remember to update those links any time you update the video.

After your video is published and the intermediate link location is set up, make the video accessible to users by adding links in the appropriate places in your documentation, such as the following:

In a related topic or procedure in the guide In a related Help topic In a Video Tutorials appendix at the end of the guide

For information about how to create links to online videos, refer to the documentation for your Authoring Tool.

Videos 233

234 Videos

18 18Glossaries

A glossary provides definitions for important and unfamiliar terms in a single, easily accessible location. These definitions help readers understand both the documentation and the software product. You can include a separate glossary at the chapter level in your documentation, or you can include a short terminology list within a chapter.

NOTE: Unless you have a specific and meaningful use case for a glossary or terminology list, we recommend that you simply define each term on its first occurrence, or provide context in the same sentence or paragraph that makes its meaning clear.

Usage guidelines for some specific terms are contained in Chapter 3, “Word Choice and Usage,” on page 75.

Section 18.1, “Glossary or Terminology List,” on page 235 Section 18.2, “Term Style,” on page 235 Section 18.3, “Definition Style,” on page 236 Section 18.4, “Term Format,” on page 241 Section 18.5, “Definition Format,” on page 241

18.1 Glossary or Terminology ListDetermine whether you need a separate glossary in a central location or a short list of key terms as a section in a larger topic:

0lossary. Use the tags in your authoring tool to create a glossary on the chapter level and format its contents. Place it as the last section in the book, followed only by an index (if your book has an index). Present the terms and definitions by using glossary-specific tags if they are available in your authoring tool. Otherwise, present the terms and definitions by using a variable list, table, or a series of paragraphs with run-in headings.

Terminology List. If you have only a few terms to define, and if they would be helpful at a particular location in your document (such as in an overview or introduction), include the terms as a section within a chapter. Present the terms and definitions by using a variable list, table, or a series of paragraphs with run-in headings.

Each entry for your glossary or terminology list has two parts: a term and a definition. The term is the word or phrase you are defining. The definition is the meaning of the term.

18.2 Term Style Define terms that are used in the documentation to mean something different from the standard

industry meaning. Define unfamiliar terms and special product or technology jargon that the reader needs to

understand to use the software. Do not define familiar terms that are used in a standard way.

Glossaries 235

Do not define field names. Such definitions belong in the user interface or documentation.

Do not define options. Such definitions belong in the documentation. Do not define compound terms where the words in the compound term are defined or

understood separately.

Define the infinitive forms of verbs, but not alternate forms.

18.3 Definition Style The definition should only define the term. Do not include an overview of the feature or

instructions for using it. Such details belong in the documentation. If applicable, include cross-references to related terms by using “See”, “See also”, or “Contrast

with” phrases. See Section 18.5.2, “Cross-References to Related Terms,” on page 242. The definition should not include cross-references to related topics or pages outside the glossary

or terminology list. You can copy a definition from any source as long as you cite the source (in a dictionary, only the

format is copyrighted).

Use the tags provided by your authoring tool when you format a glossary term and its definition.

“Defining Nouns” on page 237 “Defining Verbs” on page 237 “Defining Adjectives” on page 238

Example: align

To bring into line…

Example: computer

A programmable electronic device…

Examples: bind toenable cachingFree Form Name

Examples: binary number systembackground applicationcascading windows

Examples: scroll (not scrolling)browse (not browsing)

Example: segment

In virtual memory systems, a variable-sized portion of data that is swapped in and out of main memory.

(Source of Definition: PCWebopedia (website), Mecklermedia Corporation, 1998.)

236 Glossaries

“Defining Abbreviations and Acronyms” on page 238 “Using Abbreviations and Acronyms in Glossary Definitions” on page 239 “Expanding Definitions” on page 239 “Definition Errors to Avoid” on page 240

18.3.1 Defining NounsIn general, define the singular form of a noun in the glossary and begin the definition with an article (“a,” “an,” or “the”).

A useful definition for a noun has two characteristics:

It identifies the noun by categorizing it (usually with a synonymous noun phrase). It describes the noun by identifying the features that distinguish it from other members of that

category.

For example:

18.3.2 Defining VerbsDefine a verb by explaining the action or state of being that it expresses, its objects (if any), and its results.

Begin the definition with the infinitive form of a verb that is a synonym for the verb you are defining. Then describe the action or state of being and identify the direct and indirect receivers of the action, the effects of the action, and the performer of the action, if relevant.

Noun Category Distinguishing Characteristics

host The primary computer… …in a network or network domain.

queue element (QEL) A message… …describing one unit of work needing to be done in the context of a 327x emulator.

service profile A stored configuration… …that defines a communication service and how it behaves in the NetWare environment.

enhanced keyboard A PC keyboard… …that has 101 or 102 keys.

Verb Infinitive Synonym Receivers and Effects of the Action

configure To set up… .…a system’s external and internal components by designating the number or position of settings or devices.

install To add… …a program or programs to a system in such a way that they can run and interact properly with the other programs in the system.

load To move… …information from storage into memory for processing or for execution.

toggle To switch… …back and forth between two modes or states.

Glossaries 237

18.3.3 Defining Adjectives When possible, avoid including adjectives as glossary terms. If appropriate, include terms in

verb form rather than as adjectives.

If an adjective is used in the documentation in combination with only one noun, combine it with the noun and use the adjective-noun combination as the entry.

Begin the definition of an adjective with a descriptive participle such as “having” or a participial phrase such “pertaining to,” “relating to,” or “based on.” Then identify what noun the adjective describes and the adjective’s distinguishing features.

You can expand an adjective definition by providing an example or synonym or by breaking the described object into its parts.

18.3.4 Defining Abbreviations and Acronyms Begin the definition by spelling out the term, and end the spelled-out term with a period.

Wrong: highlighted

Right: highlight

Wrong: sans serif

Right: sans serif font

Adjective Participle or Participial Phrase

Noun Modified Distinguishing Features

asynchronous Having… …a mode of transmission…

…in which a sequence of operations is expected regardless of time.

compatible Pertaining to… …computers… …on which the same programs can be run with little or no modification.

deprecated Relating to… …terms… …that are not to be used.

stochastic Based on… …occurrences… …that are random or chance.

Example: asynchronous

Having a mode of transmission in which a sequence of operations is expected regardless of time. Asynchronous transmission takes place character by character and always contains start and stop bits to identify the beginning and end of an operation. This type of transmission is used in slower data communications environments.

Example: OS/2

Operating System/2.

A protected-mode, virtual-memory, multitasking operating system for personal computers based on the Intel 80286, 80386, and 80486 processors.

238 Glossaries

If the term is commonly used in both its abbreviated and full form, create two entries. Do not include a cross-reference to the alternate form.

When you spell out an abbreviation or acronym, present the spelled-out version as you would present it in running text. Do not use capitalization or a special font to distinguish the letters used to create the abbreviation or acronym.

18.3.5 Using Abbreviations and Acronyms in Glossary Definitions Spell out each abbreviation and acronym the first time it appears in a glossary definition.

18.3.6 Expanding DefinitionsYou can expand the definition of a term in any of the following ways: Provide a brief example or examples.

Example: QEL

queue element.

A message describing one unit of work needing to be done in the context of a 327x emulator.

queue element

QEL.

A message describing one unit of work needing to be done in the context of a 327x emulator.

Wrong: LAN (Local Area Network)

Right: LAN (local area network)

Wrong: modem (MOdulator / DEModulator)

Right: modem (modulator / demodulator)

Example: upstream

The direction of data flow from a dependent logical unit (LU) residing in a Systems Network Architecture (SNA) peripheral node toward an LU residing in a Virtual Telecommunications Access Method (VTAM) host. Contrast with downstream.

Example: host

The primary computer in a network or network domain. In Systems Network Architecture (SNA), the host is the computer or one of the computers in which a system services control point (SSCP) resides.

Glossaries 239

Briefly explain its cause or origin.

Break it into its component parts.

Point out what it is not (contrast).

Provide an analogy to a simpler or more familiar concept.

Use analogies with caution. For more information about using analogies, see Section 1.8, “Analogies, Metaphors, and Similes,” on page 27.

You can expand an adjective definition by providing an example or synonym or by breaking the described object into its parts.

Provide (limited) process information to expand the explanation.

18.3.7 Definition Errors to Avoid Avoid using a term to define itself. Use a synonym.

Example: queue element

A message describing one unit of work needing to be done in the context of a 327x emulator. The original emulator product included three components that exchanged queue elements through work queues. Although the present NetWare for SAA product contains only the first two components, and the third (Presentation Services) has moved to the workstation, the protocol of work unit messages is unchanged.

Example: service profile

A stored configuration or set of characteristics that defines a communication service and how it behaves in the NetWare environment. These characteristics include the devices on the network and the connections to those devices.

Example: enhanced keyboard

An IBM PC or PS/2 keyboard that has 101 or 102 keys. The enhanced keyboard differs from earlier IBM keyboards in having such features as 12 function keys across the top, rather than down the side, and a group of cursor-movement keys and editing keys between the main keyboard and the numeric keypad.

Example: The NDS tree structure can be compared to a tree growing upside down, starting with the name of the tree or [Root] object at the top of the tree and continuing with branches reaching downward.

Example: asynchronous

Having a mode of transmission in which a sequence of operations is expected irrespective of time. Asynchronous transmission takes place character by character and always contains start and stop bits to identify the beginning and end of an operation. This type of transmission is used in slower data communications environments.

Wrong: emulator

A software program or hardware device that emulates another device

240 Glossaries

Avoid providing definitions that begin with “when” or “where.” Use a complete sentence.

Avoid using terms or acronyms in a definition that might be unfamiliar to the reader.If you must use such terms, define them within the text of the definition, such as with a parenthetical expression.

18.4 Term Format Always use the tags provided by your authoring tool to format the term in a glossary entry. Capitalize the term in the glossary as it appears in normal text.

18.5 Definition Format Always use the tags provided by your authoring tool to format the definition in a glossary entry. In a definition you can include

Usage labels Cross-references to related entries Multiple definitions

Each of these elements is explained in the following sections.

Right: emulator

A software program or hardware device that mimics the function of another device.

Wrong: session

When two network addressable units (NAUs) communicate with each other.

Right: session

A logical connection that enables two network addressable units (NAUs) to communicate with each other.

Example: 10BASE2

The IEEE 802.3 standard for 10 Mbps baseband over thin wire (50 ohms and 200 meters).

Example: BIOS

A set of programs, usually in firmware, that enables each computer’s central processing unit to communicate with printers, disks, keyboards, consoles, and other attached input and output devices.

Example: custom data link

An upstream system connection type that allows products developed by third parties to be incorporated into the NetWare for SAA configuration.

Example: Systems Application Architecture (SAA)

An application architecture used to develop application programs for the IBM Systems Network Architecture (SNA).

Glossaries 241

18.5.1 Usage LabelsA usage label is an introductory phrase that provides the context in which the definition is valid.

Place the usage label at the beginning of a definition and follow it with a comma.

18.5.2 Cross-References to Related TermsCross-references link the terms in a glossary. Use Contrast with, See, and See also cross-references as appropriate.

Create links by using the cross-reference tags supplied by the authoring tool for that purpose. Format the cross-reference labels (Contrast with, See, and See also) in italics by using the tags

provided by your authoring tool. Link to each cross-referenced term by using the tags provided in your authoring tool. Use the

cross-reference element without a page number to create the link. Use a semicolon (;) to separate a series of cross-referenced items and sequence them in

alphabetical order, according to their appearance in the glossary or list. Use a cross-reference link without a page number

Contrast WithUse Contrast with to point the reader to a term with the opposite meaning.

See A See cross-reference appears by itself with no definition. It can refer the reader from an

obsolete term to its current equivalent or from a general term to a more specific one.

See is also used in an acronym or abbreviation definition to point to the spelled-out version of the term.

Example: index

In SQL, a field or combination of fields used to sort a table into a particular order.

In Btrieve, a group of bytes characterized by offset and length to provide direct access to a data value.

Example: downstream

The direction of data flow from a logical unit (LU) residing in a Virtual Telecommunications Access Method (VTAM) host system toward a dependent LU resident in a Systems Network Architecture (SNA) peripheral node. Contrast with upstream.

242 Glossaries

Avoid using a See cross-reference in place of a full definition for an acronym or the expansion of an acronym. Give the full definition in both places.

See AlsoUse See also to point the reader to a term or terms with related but not synonymous meanings.

18.5.3 Multiple Definitions If a term has more than one definition, list the term once and give each definition in a numbered

paragraph underneath.

When a term has two or more grammatical functions, list the term once and give each definition in a numbered paragraph underneath, where you also specify the part of speech (such as “noun,” “verb,” “adjective.”)

Example: global group

See authorized group.

Example: profile

See LAT node profile; service profile.

Example: SNACP

See SNA control point.

Example: emulator

A software program or hardware device that provides the function of another device. See also terminal emulator; TTY emulator.

Example: entity name

In an AppleTalk network, the form of symbolic name used to identify servers independent of their hardware. See also domain name.

Example: session 1. A connected exchange of related messages between one user and one application.

See also LU-LU session; SSCP-LU session.

2. The description of the means and resources needed to create a session, including the logical unit (LU) number to be used and the display station model. Each configured session or LU is presented as a datagram node.

Example: block 1. (noun) The smallest amount of disk space that the server reads or writes at a time. All

disk accesses are measured in blocks. The block size for a volume is defined at installation, and is usually between 4 KB and 64 KB.

2. (verb) In NetWare software, to render inoperable or untouchable or unchangeable; to obstruct access to an eDirectory object, such as a directory or file.

3. (verb) To select or highlight text.

Glossaries 243

244 Glossaries

19 19Indexes

Indexes are useful for a topic-based view into help topics, but they are not a standard element in online documentation. Use the guidelines in this section to index content if your doc development tools support indexing systems.

Section 19.1, “Index Style,” on page 245 Section 19.2, “Index Entries,” on page 246 Section 19.3, “Index Content,” on page 246 Section 19.4, “Index Implementation and Maintenance,” on page 248

19.1 Index StyleFollow these index style guidelines:

Use the plural form of nouns, unless it is a mass noun (such as “email”) or there is only one of the thing (such as the Sent Items folder in GroupWise).

Use the gerund form of verbs.Plural nouns and gerund verbs reduce potential ambiguity between nouns, verbs, and adjectives that have the same base form for multiple parts of speech. For example, “access” could be a noun or a verb, and “secure” could be an adjective or a verb. By using plurals and gerunds, you can easily create separate primary entries for different parts of speech.

Use lowercase for index entries (both primary entries and secondary), unless an entry is a proper noun such as a program name, feature name, and so on.

Use the same style conventions (spelling, hyphenation, capitalization) that you use in the document you are indexing.

Omit articles, unless they are required for clarity.

Examples: connectionsemailsecuritySent Items folderserversWeb Interface

Examples: creatingloadingrevokingsecuringtroubleshooting

Indexes 245

19.2 Index Entries Do not use more than two levels of indexing: primary and secondary. For primary entries, use specific and meaningful nouns or noun phrases and gerunds, even for

processes or actions. For secondary entries, use specific and meaningful nouns or noun phrases, gerunds, or

adjectives. Make each primary entry as specific as possible in order to avoid long lists of secondary entries. Avoid extremely general terms, such as “commands,” “properties,” “diagrams,” “displaying,” and

“editing.” However, some generalities are useful to index, as discussed in Section 19.3, “Index Content,” on page 246.

Do not create a primary entry that has only one secondary entry. Combine them, unless the secondary entry is a See reference.

You can use a “see” or “see also” reference to redirect users to a related term in the index, where they can look up pertinent alternative entries. A See reference appears by itself with no other secondary entries. It can refer the reader

from an obsolete term to its current equivalent, from a general term to a more specific one, or from an acronym or abbreviation to the spelled-out version of the term.Pick one approach and apply it consistently: Create a “see” entry in every topic where the synonym appears. Create one “see” entry that points to the most pertinent topic, and allow users to

independently look up the synonym for more information. A See also reference refers the reader to a term or terms with related but not synonymous

meanings.

19.3 Index ContentPlanning your index makes it easier to tag content to build the index in your authoring tool. Review the document to determine what primary entries and secondary entries you need. Create a draft of your index in a word processor.

For convenience in editing your draft index, you might want to create your draft in multiple word processing files so you can move from place to place in your draft index as you build it, without searching or scrolling very far as you add and revise entries. For a large index, one file per letter can work well. For a smaller index, you can group several letters into the same file. Do your best to create the “final” index before you start adding elements to topics.

Identify and list categories of information relevant for your product and target industry:

General concepts

Examples: appointmentsemailcalendarstime zones

246 Indexes

Product-specific concepts

General tasks

Specific tasks

Conditions

Program names

Feature names

Examples: categoriespersonal address booksproxy usersrules

Example: configuringdeletinginstallingplanningregisteringrepairingsecuringstartinguninstalling

Example: delegating appointmentsfinding contactssending messages

Example: automaticcustomdefaultofflineundeliverable

Example: FirefoxGroupWise CheckNotifySkype

Example: Auto-DateAuto-SaveBusy SearchCaching modeFindQuickViewer

Indexes 247

Next, identify as many alternative terms as you can think of:

Synonyms Industry standard terms for things that have custom terms in your product Terms used by other popular products for features in your product

Review the list and add more entries:

Create reversals, such as “rules, vacation” as a reversal of “vacation rules.” Think from the point of view of the user instead of someone who knows the product well.

Finally, review the index repeatedly:

Make sure that you add new entries as you think of them. Find and change inconsistencies.

19.4 Index Implementation and MaintenanceMaintaining indexes can be difficult if authoring tools do not provide a convenient way to keep track of and edit entry elements after you have inserted them. Ensure that you consciously maintain their integrity as you edit, share, or profile a topic. For easier maintenance, follow these best practices as you place the indexing elements in a topic:

Put all index entry elements that pertain to a particular topic immediately under the parent heading, rather than scattering them throughout the topic.

To help you determine the best topic location for the index entry elements, search for the term in the PDF of the document and carefully select the most pertinent instances. Major topics have at least one index entry element. High-level sections have fairly general index entries. Lower-level sections have more specific index entries.

As you insert index entries in a topic, you can insert a hidden remark under the heading to indicate whether you have finished indexing the heading or whether more elements should be added.

After you set up index entries, generate the Help index and check for inconsistencies, duplication, and gaps. Compare it to your draft index to ensure that the generated index accurately reflects, or improves upon, the draft index.

When you maintain and add information to documentation as the product matures, review your indexing system to ensure that your indexes accurately reflect content.

248 Indexes

20 20Help

Follow these guidelines for presenting information about help systems.

20.1 Help Terminology Avoid the term online Help. Instead, use Help to refer to an online help system.

Capitalize the word Help only when it refers to a specific online help system.

20.2 Handling Help in Mobile AppsEngineers are developing more mobile apps to complement existing Micro Focus applications or to provide additional access to end users. You might be required to provide help in some format for those mobile apps.

Mobile apps should use standard navigation that is well-known to mobile app users, and that is self-explanatory to use. Actions typically follow usability standards for the target mobile platform, such as Apple iOS and Android.

Follow these guidelines when preparing help for mobile apps:

If how to access and use a feature is not intuitive, work with your team to improve its usability so that documentation is simplified or unneeded.

Work with developers to provide progressive coach marks (hints) in the UI that appear on the first launch for new users, one at a time, as the user reaches the relevant section of the app. Keep hints helpful, scannable, and sparse. Don’t explain the obvious. Use short text or visual tips that are easily distinguished from interactive elements in the UI. Coach marks should not be a substitute for poor design.

In keeping with a targeted-documentation approach, do not provide help for commonly used or familiar tasks that users can easily figure out.

Provide help for tasks that users perform only once or infrequently, or if usage is not obvious.For example, provide help for tasks to register or deregister the mobile device with a service.

Example: For more information, refer to the Tempo Help.

Example: Search the Help for more information.

Example: Check the most recent help files into the appropriate build directory.

Example: Tap to turn pages

Example: Add new friends

Example: ← Statistics Expenses →

Help 249

Publish Help for the mobile app to your online documentation website, then add a Help option in the app menu system that links to the online Help. The Help link or icon should be compatible with whatever menu system developers devise, including tabs, tabs with a More option, progressively collapsing menus, scrollable navigation, side-bars, drop-down menus, or hamburger menus.We discourage using integrated help files because it increases the size of the app and requires new releases of the app to update content. Adding help files to the iOS and Android platforms are different processes, which complicates exporting help in the appropriate format for each.With online Help, the size of the mobile app does not increase, and the help files are always current. It is easier to update the website than to update the app for a help content change. If your team already has a solution in place, you are not required to change to this model, but consider this approach for new mobile apps.

250 Help

21 21Developer Documentation

Developer documentation should follow the guidelines in the other sections of the Style Guide, with the exceptions and differences listed in this section.

Section 21.1, “General Developer Doc Guidelines,” on page 251 Section 21.2, “Programming Elements,” on page 251 Section 21.3, “Reference Material,” on page 253 Section 21.4, “Examples,” on page 254 Section 21.5, “Revision Histories,” on page 254

21.1 General Developer Doc Guidelines To be more solution-oriented in our documentation, use “benefits” rather than colloquialisms (for

example, “features” or “functionality”). The first time a function or topic within a book is referenced within a section in the same book,

provide a link. To make our documentation as easy to navigate as possible, provide linked lists for every

subsection within a document. Some authoring tools offer a SubToc element that automatically generates the linked list to the next lower level of topics.For example, when you start a new topic, you should provide a linked list of all the subheadings within that topic. (An exception is lists to RefEntries, which could number into hundreds or more and become impossible to manage. Indexes can be produced for those.)

In tables, list the constant (such as the flag name) in the first column and the values in the second column. List only the decimal values. In most cases hexadecimal values are used only for debugging.

For C manuals, use all capital letters on NULL in all instances (both running text and code). For Java, capitalize null as appropriate. In general, use NULL in all cases unless you are writing documentation for the Java language.

“API” refers to a set of related functions, classes, and so forth. “Function” refers to the entity (usually in the C language) that performs a specific task within an API. Do not use the term “API,” “routine,” or any other general term when you mean “function.”

21.2 Programming Elements Section 21.2.1, “Identifying Programming Elements,” on page 252 Section 21.2.2, “"Function" or "API"?,” on page 253

For more information about style guidelines for programming elements, see Chapter 5, “Computer Elements,” on page 151.

Developer Documentation 251

21.2.1 Identifying Programming ElementsProgramming elements include such items as the following:

Functions Parameters Structures Classes Interfaces Methods

In running text, headings, and index entries, do not include empty parentheses after method or function names.

Do not tag programming elements by using <Function>, <Parameter>, and so on. In reference documentation, you do not need to provide much guidance about which is which because the reader has the prototype to look at. However, non-reference material provides less context. When writing non-reference material, follow these guidelines.

Use the programming term (such as “function,” “method,” and so forth) when introducing a programming element and when the verb or context does not make the subject clear (for example, “the atexit function”). These situations typically arise when you are describing the element rather than doing something with it.

After the programming element has been introduced, its name can generally be used alone, especially when it is used with a verb such as “call” or “set.”

NOTE: To avoid confusion, be especially careful when discussing a programming element that has a name that is also a word, such as “open.”

Provide a link to the reference page for the programming element where helpful.

For example, if you write “ContextHandle enables you to…” the reader would not know whether you are referring to a Java object, interface, or method. In C, naming standards are less consistent, leading to even more confusion. If this is the first time you refer to ContextHandle, something like “The ContextHandle function enables you to…” is better. If you then refer to ContextHandle again in the same section, you can let the name stand alone.

However, if you write “Calling ContextHandle establishes …” or “Implement ContextHandle to …”, the verb conveys the meaning of the programming element that you are referring to.

Wrong: The NXScheduleDelayedWork ( ) function creates...

Right: The NXScheduleDelayedWork function creates...

Example: The ContextHandle function establishes a session and returns a context handle to your application. During session initialization, calling ContextHandle notifies the registry of your intent to abend the server. If the returnTrue parameter is set to 1, ContextHandle returns true. Otherwise, ContextHandle returns false

252 Developer Documentation

21.2.2 "Function" or "API"?When you are discussing C programming, use the following guidelines:

Use “function” for a C function provided to the developer.

NOTE: Occasionally developers are instructed to write their own functions for specific purposes.

Use “API” for a set of functions that provides an interface for the programmer. Use “routine” to describe a generic section of code that accomplishes a defined task.

For example, LibC provides a math API that includes the sin function. The developer can use sin in a routine to determine a sine value.

21.3 Reference MaterialReference material in a developer guide might include description pages for C functions, structures, and so on; Javadoc references; HTML references for ActiveX controls; and eDirectory schema class, attribute, and syntax descriptions.

Use the following guidelines when you create reference material for any API:

If a reference chapter seems too large and unwieldy, consider dividing functions into logical functionality groups. You can then provide an A-Z view using generated indexes.

RefPurpose elements should contain a brief description of what the function (or object) does or is and should end in a period. Unessential information should appear in the remarks section. This element is not more than one paragraph; do not try to force it into multiple paragraphs by using hard returns.

If you have specific requirements or dependencies that vary from function to function within the same book, use RefClass elements to specify these requirements.

It is better to list the #include statement as part of the Syntax section rather than in a separate “Defined In” RefClass element, for example.

Do not list empty sections. For example, remove any sections that simply state None. Developers realize that a void data type for parameters or return values means that no values are needed or expected in those cases.

The description for each C parameter should begin with “Specifies” or “Points to.” If there are more than two columns in a ReturnValues table, the table must have a header row.

The default column arrangement should be Value, Flag, Description (unless the use of your document dictates a different arrangement). Be consistent.

The See Also section should contain a list of functions ordered by their appearance in the document. Coordinating concepts should be linked from the Remarks section.

As much as possible, list snippets showing how to call each function in the reference documentation under an Example section. Longer code samples that are fully compilable should be submitted to the Developer website as sample code files and linked to from the documentation (these must be maintained and it is extremely difficult to do that within documentation).

If you have a structure with alternative names, document the name specified by the most-used function. Within other function's syntaxes, document the name specified in the header file for that function without a corresponding link. Then, in the Parameters section, add a note that contains a link to the structure with an explanation that the structure has more than one name.

Developer Documentation 253

21.4 Examples Novell Developer Kits website (http://www.novell.com/developer/ndk/).

Libraries for C (http://www.novell.com/developer/ndk/libraries_for_c_%28libc%29.html).

21.5 Revision HistoriesFor developer documentation, a simple table is generally used (Release Date/Changes). However, if you have so many changes within a revision that your Revision History becomes unwieldy, you can consider other formats. The changes are displayed in reverse chronological order so that the most recent changes are most accessible.

254 Developer Documentation

http://www.novell.com/developer/ndk/

http://www.novell.com/developer/ndk/libraries_for_c_%28libc%29.html

IV IVAppendixes

The appendixes provide checklists and examples that expand on the style guidelines.

Appendix A, “Preparing Documentation for Editing: A Checklist,” on page 257 Appendix B, “Writing and Usage Examples,” on page 259 Appendix C, “Project Style Sheet Example,” on page 273 Appendix D, “Product Terminology,” on page 275 Appendix E, “Documentation Updates,” on page 291

Appendixes 255

256 Appendixes

A APreparing Documentation for Editing: A Checklist

Use the following basic checklist to ensure that your documentation is ready to hand off to an editor. You can also review the Style Guide, especially Chapter 3, “Word Choice and Usage,” on page 75, and use past edits to add other items as necessary to personalize the list.

Status Task

1. Run Spell check.

Spell check does not find errors for correctly spelled but wrong words, such a manger instead of manager, missing or improper hyphenation, idiomatic expressions, or capitalization of proper nouns. You should recognize and correct such errors in context as you write.

2. Search for the following words or phrases and replace them as necessary:

once: For most occurrences, use “when” or “after.” Use “once” only to mean “one time.”

have to, need to, must: Use “need to” or “must” instead of “have to.”

may: Reserve “may” for use in cases where permission is sought or given, such as in a legal statement. Use “can” to express ability, “might” or “could” to show a possibility, and “perhaps” to express a subjunctive mood.

while: “While” means “for a period of time,” “as long as,” or “during the time that.” Use it to indicate a time relationship. Do not use it as a substitute for “and,” “but,” or “although.”

due to: Use “because of” instead of “due to.”

back up, backup: Two words when used as a verb, one word when used as an adjective or noun.

log in, login: Two words when used as a verb, one word when used as an adjective or noun.

set up, setup: Two words when used as a verb, one word when used as an adjective or noun.

3. Ensure that you are using the simple present tense most of the time. (Search for the word “will” and check its usage in context.)

For more information, see Section 1.43.2, “Verb Tense,” on page 66.

4. Check for antecedent problems with the word “using.”

For more information, see Section B.8, “Using the Word “Using” in Documentation,” on page 270.

5. Use “which” to introduce nonrestrictive clauses and use “that” to introduce restrictive clauses.

For more information, see Section B.4, “That and Which,” on page 264.

Preparing Documentation for Editing: A Checklist 257

6. Ensure that you are using “they” and “their” as plural pronouns instead of singular pronouns.

Writers sometimes attempt to avoid gender problems in writing by using “they” and “their” as gender-neutral singular pronouns, such as “A user can start their computer by...” There are several suggestions for avoiding this difficulty in Section B.6, ““Their” as a Gender-Neutral Singular Pronoun,” on page 267.

Status Task

258 Preparing Documentation for Editing: A Checklist

B BWriting and Usage Examples

This section provides additional examples for the style guidelines in earlier sections.

Some of the information was originally published as a series of email Editing Notes and therefore retains a less formal style than other sections in the Style Guide

Section B.1, “Adverbs,” on page 259 Section B.2, “Introductions,” on page 260 Section B.3, “Only,” on page 264 Section B.4, “That and Which,” on page 264 Section B.5, “Type or Enter,” on page 266 Section B.6, ““Their” as a Gender-Neutral Singular Pronoun,” on page 267 Section B.7, ““Then” as a Conjunction and as an Adverb,” on page 268 Section B.8, “Using the Word “Using” in Documentation,” on page 270 Section B.9, “Verb Tense,” on page 271 Section B.10, “CPU vs. Processor,” on page 272 Section B.11, “RAM vs. Memory,” on page 272

B.1 AdverbsMany adverbs can move from place to place in a sentence without changing the meaning.

However, this flexibility can sometimes be confusing, or it can sound awkward.

In fact, the adverb “only” can move to a dozen different locations in a sentence, each one with a different meaning. (For examples, see Section B.3, “Only,” on page 264.)

The confusion most often comes when the adverb loses contact with the word it modifies. Rewrite the sentences so the adverb is closer to the verb it describes (usually just before or just after, depending on the meaning you want).

Example: Mary walked slowly to class.Mary slowly walked to class.Mary walked to class slowly.Slowly, Mary walked to class.

Example: Mary walked to class and talked with her friends slowly.

Example: You must reboot the local domain controller manually after the installation is complete.

Example: Mary slowly walked to class and talked with her friends.

Example: You must manually reboot the local domain controller after the installation is complete.

Writing and Usage Examples 259

B.2 IntroductionsIntroductions to tables, graphics, lists, procedures, and SubTocs should be concise and meaningful. Too often, they contain redundant or wordy text.

As you evaluate introductions to see whether you can eliminate or reword them, use the following guidelines:

Is the wording redundant with titles that precede or follow the introduction? Does the introduction contain information that’s obvious in context, such a separate sentence

mentioning “the following graphic” or “the following table”? Remember that your purpose is not just to reduce the number of words, it is to ensure that your

writing is clear, concise, and helpful to the user. To make the best use of your time and to avoid localization costs, do not go into existing doc and

update it simply for the sake of rewriting introductory phrases. Make changes in existing doc only when it is being revised for other reasons.

Section B.2.1, “Introducing Tables and Graphics,” on page 260 Section B.2.2, “Introducing Procedures,” on page 262 Section B.2.3, “Introducing SubTocs,” on page 263 Section B.2.4, “Introducing Lists,” on page 263

B.2.1 Introducing Tables and GraphicsRedundant or wordy text should be deleted or rewritten.

“Example 1: Redundancy Times Three” on page 260 “Example 2: Deleting Redundant Phrases and Revising Headings or Titles” on page 261 “Example 3: Deleting the Heading” on page 261 “Example 4: Rewriting the Introduction” on page 261 “Example 5: Using a Table without a Title” on page 261 “Additional Examples” on page 262

Example 1: Redundancy Times Three Many redundant or meaningless introductions follow a heading, especially when the introduction is a transition to an item with its own heading, such as a graphic or table. In the following example, the heading, introduction, and table title repeat the same information three times:

Events That Trigger a Rule [heading]

The following table shows the actions that trigger a rule: [introduction]

Table 9-1 Events That Trigger a Rule [table title]

260 Writing and Usage Examples

Example 2: Deleting Redundant Phrases and Revising Headings or TitlesIf the section heading contains all the information needed to introduce the table, you can leave out the introductory phrase. You should also rewrite either the section heading or the table title so that the wording is not identical in both.

Example 3: Deleting the HeadingIf this is the only table under this heading, you might be able leave out the section heading, and let the table title stand on its own.

Ensure that leaving out a heading doesn’t create inconsistency in the structure of the document. For example, if there are three parallel headings in a document, and one of them contains the table you are evaluating, you shouldn’t delete one of the parallel headings to avoid redundancy. Use one of the other suggestions instead.

Example 4: Rewriting the IntroductionYou can rewrite the introductory sentence so it provides a more meaningful introduction to the material in the table or graphic. You should also rewrite one of the titles so that the wording is not identical in both.

Example 5: Using a Table without a TitleStyle Guide rules now allow writing teams to use tables without titles if the usage is consistent throughout a book. See Section 12.1, “When to Use Table Titles,” on page 203 and Section 12.2, “Guidelines for Using Table Titles,” on page 204.

Selecting Rule Triggers [heading]

Table 9-1 Events that Trigger a Rule [table title]

[no heading]

[no introduction]



There are several events that can cause a rule you create to be activated. In addition, you can limit the items that are affected by a rule. [introduction]



There are several events that can cause a rule you create to be activated. In addition, you can limit the items that are affected by a rule. [introduction]

[no table title]


Additional ExamplesEnsure that your introduction is concise, but still provides context for the user.

B.2.2 Introducing ProceduresAn introductory phrase is not required for procedures, but you can use one as a transition between the heading or explanatory text and the actual procedure.

Ensure that you don’t just reiterate information already given in a heading. You can start a procedure immediately under a heading, if the heading provides accurate and adequate information. In the following examples, the introductory phrases should be deleted.

If the introductory phrase adds more information, or comes after a longer introductory paragraph and is a useful transition to the procedure, leave it in place.

Original: The following table lists the fields that are contained in the header:

Revised: The following fields are contained in the header:

Original: Four links are displayed, as shown in the following figure:

Revised: Four links are displayed.

Original: The icons that appear next to items show information about the items. The following table explains what each icon means.

Revised: The icons that appear next to items show information about the items.

Wrong: Configuring Basic SMTP/MIME Settings

To configure SMTP/MIMIE settings:1. This is the first step.

Wrong: Configuring How the Internet Agent Handles Email Addresses

To configure how the Internet Agent handles email addresses:1. This is the first step.

Right: Enabling LDAP Services

To enable and configure LDAP services for mail client access:1. This is the first step.

Right: Protecting Against Spam

Introductory paragraph under the heading: Multiple unsolicited messages (sometimes called spam) from the Internet can potentially harm your GroupWise messaging environment. You can use the settings on the SMTP Security page to help protect your system from malicious or accidental attacks.

To configure the SMTP security settings on the mail server:1. This is the first step.


When you use an introductory phrase, resist the temptation to make it a complete sentence by adding “complete the following steps.” It’s extra wording that’s unnecessary in context.

B.2.3 Introducing SubTocsThe SubToc element in some authoring tools automatically generates linked lists to the next level of sections within a section. In published documentation, Micro Focus Style recommends that you rely on the bookmarks or navigation links instead of inserting SubToc elements in the body of the section or HTML page. Be consistent in usage within your doc set.

NOTE: SubTocs can be useful navigation aids when you work in the DocSys/FrameMaker authoring tool. If you profile the SubToc elements to omit them in published documentation, ensure that you omit introductory phrases that refer to them, or also profile them out.

Some common introductions to SubTocs are obvious in context and do not provide helpful information to users:

One solution is to leave out the introductory phrase, especially if the heading provides sufficient information. Some authoring tools provide an attribute for the SubToc element that inserts a title automatically, such as “In This Section”.

Another solution is to include an introductory paragraph to provide meaningful information about its content.

B.2.4 Introducing ListsIntroductions to lists should also be evaluated to ensure that they provide meaningful information that is not obvious in context.

Wrong: To configure the ARAS for loading, complete the following steps:

Right: To configure the ARAS for loading:

Example: This guide contains the following sections:

Example: This section contains the following topics:

Example: This section contains the following information:

Example: This guide explains how to install, configure, and manage the Identity Manager Driver for LDAP.

Example: You can adapt GroupWise to your specific needs by archiving and backing up messages, changing your password, repairing your mailbox, and more.

Example: The GroupWise Linux/Mac client includes several key enhancements:

Original: The driver can use either of two publication methods to recognize data changes and communicate them to an Identity Vault, as shown in the following list:

Revised: The driver can use either of two publication methods to recognize data changes and communicate them to an Identity Vault.


B.3 OnlyIt’s only an adverb, but this one word seems to slide elusively from one place to another in a sentence, changing the meaning of the sentence with each relocation.

To quote Merriam Webster’s Collegiate Dictionary, Tenth Edition, with italics added to emphasize the statement that is pertinent to our documentation: “The placement of ‘only’ in a sentence has been a source of studious commentary since the 18th century, most of it intended to prove by force of argument that the prevailing standard usage is wrong. After 200 years of preachment, the following observations may be made: the position of ‘only’ in standard spoken English is not fixed, because ambiguity is avoided through sentence stress...in edited and more formal prose, ‘only’ tends to be placed immediately before the word or words that it modifies.”

B.4 That and WhichOur guideline is to use “that” to introduce restrictive clauses, “which” to introduce nonrestrictive clauses, and “who” to introduce either if humans are involved.

The key to understanding when to use “that” and when to use “which” is understanding when a clause is restrictive and when it is nonrestrictive.

Section B.4.1, “Restrictive Clauses,” on page 265 Section B.4.2, “Nonrestrictive Clauses,” on page 265 Section B.4.3, “But What's Essential?,” on page 265 Section B.4.4, “Using “Who” in Computer Documentation,” on page 266

Original: The following list contains all of the packages and classes included in the Java 2D API. Each item in the list is linked to its respective API documentation.

Revised: The following packages and classes are included in the Java 2D API. Each item in the list is linked to its API documentation.

Original: The following list describes the configuration options available in iPrint:

Revised: There are five configuration options available in iPrint:

Example: Only the Supervisor has rights to manage the users on the appliance. The only Supervisor has rights to manage the users on the appliance.The Supervisor only has rights to manage the users on the appliance.The Supervisor has only rights to manage the users on the appliance.The Supervisor has rights only to manage the users on the appliance.The Supervisor has rights to only manage the users on the appliance.The Supervisor has rights to manage only the users on the appliance.The Supervisor has rights to manage the only users on the appliance.The Supervisor has rights to manage the users only on the appliance.The Supervisor has rights to manage the users on only the appliance.The Supervisor has rights to manage the users on the only appliance.The Supervisor has rights to manage the users on the appliance only.


B.4.1 Restrictive ClausesA restrictive clause is a modifier that is essential to the meaning of the sentence. It is not set off with commas.

B.4.2 Nonrestrictive ClausesA nonrestrictive clause is parenthetical and is not essential to the meaning of the sentence. To show that the clause can be omitted from the sentence, set it off with commas.

B.4.3 But What's Essential?It’s sometimes tricky to decide what is “essential” and what is “nonessential.” Is not almost everything we write essential to understanding how software works?

It can be helpful to think in terms of “Is everything in this category involved, or is it restricted to just a subset?” If it’s everything, the clause is nonrestrictive (nonessential). If it’s a subset, it’s restrictive (essential).

Older persons who take many different kinds of medications are subject to cross-reactions. [Restrictive. Only the subset that takes many medications has the problem.]

Older persons, who take many different kinds of medications, are subject to cross-reactions. [Nonrestrictive. Assumes that all older people take medications.]

Determining how many are involved can also point out cases where making a clause restrictive creates inaccuracy.

My wife who is at home will answer your question. [Making this restrictive implies more than one wife, and the one who is at home will answer the question.]

My wife, who is at home, will answer your question. [Nonrestrictive. There’s only one of them, and she happens to be at home.]

Session cookies are not enabled for the Web Clipping interface that does not support them. [There’s more than one Web Clipping interface, and this sentence describes the one that does not support session cookies.]

Session cookies are not enabled for the Web Clipping interface, which does not support them. [Only one Web Clipping interface, and it does not support cookies.]

The proposal that was 100 pages long was delivered on time. [Several proposals. The 100-page one was on time.]

The proposal, which was 100 pages long, was delivered on time. [One of them, it was delivered on time, and it happened to be 100 pages long.]

Example: The instructions that reside in memory run the program text.

Example: An assembler is a computer language that parses symbolic statements, verifies syntax, interprets semantics, and creates machine language code.

Example: You can view a spreadsheet equivalent, which contains more information than is available in a graph.

Example: The login instructions, which reside in memory, are executed first.


The store honored the complaints, which were less than 60 days old. [A group of complaints, all were honored, and they were less than 60 days old.]

The store honored the complaints that were less than 60 days old. [A group of complaints, but only part of them were honored.]

Try it for yourself. How would the meaning change if you switched the clauses in the following sentences from restrictive to nonrestrictive? Try it by switching “which” for “that.” (And, of course, adjusting the punctuation accordingly)

The credit card is in my wallet, which you can find in the kitchen drawer. The boat that sailed on October 25 is the one referred to in the contract. The house that is painted pink has just been sold. The microcomputers, which arrived yesterday, must be adjusted. The brawl that began in a dispute over spelling lasted longer than the brawl that began after an

argument about Wittgenstein. Give me the book that is on the table. The surgeons reconstructed his larynx, which had received a traumatic injury. All laughter that is out of place will be prohibited. The council invalidated certain portions of the treaty, which gave the USSR the right to intervene

in Iranian affairs

B.4.4 Using “Who” in Computer DocumentationThe general guideline for both restrictive and nonrestrictive clauses is to use “who” if humans are involved.

For example, “I prefer to share the road with drivers who focus on the road.”

However, in computer documentation, it is sometimes difficult to ascertain whether something is a human or a machine. In those cases, use “which” or “that” as appropriate. For example, a computer can sometimes act as a user to create automated responses within an email system. If you do not know or aren’t sure, use “which” or “that.”

For example, “Create a user that has all administrative rights.”

B.5 Type or Enter“Type” and “Enter” have different meanings, and we should ensure that they are correctly used in our documentation.

“Type” means to use the keyboard to add information, whether it’s in a word processor, a field, a command prompt, or wherever.

“Enter” means to use the keyboard to add information, and then to press the Enter key.

In non-technical usage, we’re used to seeing the two words used as synonyms, so we don’t think about using the Enter key (or maybe even the keyboard) when we’re told to “Enter your name on the first line of the application.”

However, we need to be more accurate in our technical documentation. When a user is adding information to fields in a dialog box or a wizard, the phrase “Enter the user’s name” is inaccurate if pressing Enter would close the dialog box before all of the necessary information in the other fields is in place.


Also, remember that “type” is not always the best alternative, because it can be too specific if information can be added to a field in several different ways, such as typing, selecting from a list, or copying and pasting. If this is the case, you should use a word like “specify” or “provide,” which leaves the choice of method up to the user.

One additional reminder: If you use “type,” use just the single word “type” instead of “type in.” If you say “Type in the information,” it can be construed to mean that you’re telling the user to type something “in the information,” which presents an amusing but inaccurate image. On the other hand, “Type the information in the field” is accurate.

B.6 “Their” as a Gender-Neutral Singular PronounMini-Quiz: Read the following sentences, identify what they have in common—and identify what’s wrong. Then look at the alternate wordings following the quiz.

Users need to reboot their computer. Users should have sufficient rights to install applications to their workstation. If users minimize the Application Window, they will have access to their normal desktop. Each person should ensure that their head is protected from the weather. Someone left their report on the table.

Of course, it’s the incorrect combination of the plural pronoun with a singular antecedent. Although some of the uses might be within the realm of possibility (maybe we have several people with a single computer, or several people who wrote one report), it’s highly unlikely that we have several people with joint custody of one cranium.

There are several possibilities for rewriting:

Make everything plural Users need to reboot their computers. Users should have sufficient rights to install applications to their workstations. Participants should ensure that their heads are protected from the weather.

Make everything singular The user needs to reboot his or her computer. Each of you should ensure that your head is protected from the weather. If you minimize the Application Window, you have access to your normal desktop.

Use a definite or indefinite article instead of the pronoun “their” Someone left the report on the table. Users should have sufficient rights to install applications to a workstation. If users minimize the Application Window, they have access to the normal desktop.

Chicago has confirmed this guideline, as indicated in the following Q&A from their website.

Q. I would swear that I saw a reference in your manual that approved of the use of “their” instead of a gender-biased singular pronoun. For example, “If the user has completed installing the program, they should put the CD-ROM back in the package,” instead of “If the user has completed installing the program, s/he should put the CD-ROM back in the package,” but on your Q&A, you dance around the answer to the question and suggest that you do NOT approve of the singular “their.” Can you tell us what is acceptable?


A. Yes, you saw it at 2.98 (note 9) in the fourteenth edition, but there was some regret at having written it, and we decided not to second the idea in the fifteenth edition. Though some writers are comfortable with the occasional use of “they” as a singular pronoun, some are not, and it is better to do the necessary work to recast a sentence or, other options having been exhausted, use he or she. For a fuller discussion of this issue, see paragraphs 5.43 and 5.202-6 in CMS 15, including the entry for “he or she” under the “Glossary of Troublesome Expressions” at paragraph 5.202.

Q. PLEASE tell me what you are recommending when people need a gender-neutral singular possessive pronoun. In order to avoid saying “his mind” or “her mind” (or, God forbid, “his/her mind”) people are saying “their mind”—and it blows MY mind—unless, of course, those people could ensure that “they” are “of one mind”! If you have a discussion on this issue, I’d be most happy to receive it or be directed to it.

A. I'm afraid your gender-neutral pronoun (at least in the sense you need) does not exist in our lexicon. I agree that the plural pronoun with a singular noun seems inadequate; I would suggest that you recast the sentence altogether or at least make “mind” plural for agreement: their minds. Other writers alternate between using “his” and “her” in such constructions in order to give equal status to each pronoun.

Additional notes on this discussion:

The Style Guide specifically prohibits such usages as “s/he” or “he/she,” and also prohibits alternating between pronouns. For more information about what to avoid and how to rewrite problem usages, see Section 1.16.3, “Sexist Language,” on page 40.

Refer to Sections 5.225 to 5.230 of Chicago for gender-neutral writing techniques.

B.7 “Then” as a Conjunction and as an AdverbThe word “then” has two common uses in our documentation:

Section B.7.1, “Using “Then” as a Correlative Conjunction,” on page 268 Section B.7.2, “Using “Then” in Procedures,” on page 269

B.7.1 Using “Then” as a Correlative ConjunctionFrom Chicago, 16th Edition. Section 5.195:

“Correlative conjunctions are used in pairs, often to join successive clauses that depend on each other to form a complete thought. Correlative conjunctions must frame structurally identical or matching sentence parts; in other words, each member of the pair should immediately precede the same part of speech.”

Correlative conjunctions can join words or phrases.

Combining “if” and “then” as correlative conjunctions is a bit tricky for many people.

Example: Either you must follow the doctor’s advice or you must bear the consequences.

Example: Either John or George must have done this mischief.

Example: Neither the life of an individual nor the history of a society can be understood without understanding both.

Example: They not only read the book but also saw the movie.

Example: It was neither clever nor funny.


When the two clauses do not have identical construction, you do not need the word “then.” “If” is simply a conjunction at the beginning of an introductory clause or phrase.

Remember that this is a small point of grammar that's not going to cause any problem for users; in fact, they probably won't even notice what we're calling a “mistake.” If you find an instance as you write, correct it, but don't spend a lot of time searching and replacing in current documentation, and definitely don't go back and correct older docs.

B.7.2 Using “Then” in ProceduresWhen we use the word “then” in procedures, it's an adverb, so it doesn’t use the same rules as when it's used as a conjunction. In both cases, “then” conveys a sense of time and indicates that something is happening in sequence. But in procedures, it's not paired with another word, as it is when it functions as a correlative conjunction. It simply signals that the user is coming to the last action in a sequence.

The rule from the Style Guide says “When describing actions that a user takes within a dialog box or property page, use a series separated by commas. Use ‘then’ as the transition into the last item of the series.”

If the step has only two actions, it is okay to join them with “and.” However, using “then” is probably better because it's consistent with other steps.

See Section 11.3.4, “Combine Multiple Actions,” on page 197 for more examples.

Example: If the first claim is true, then the second claim must be false.

Example: If you choose to do your best, then you will feel satisfied.

Example: If you tell Estelle, then she will tell Philip.

Example: If I use proper grammar in my essay, then I will earn a higher grade

Example: If the weather is nice, we usually go swimming.

Example: If there is milk in the refrigerator, I'll have milk with my cake.

Example: If the phone doesn't ring, I can take a nap.

Example: If we fail, the project stops.

Example: Provide your username and password, select a server from the drop-down list, specify a tree, then click OK.

Okay: Edit the field and press Enter.

Better: Edit the field, then press Enter.


B.8 Using the Word “Using” in DocumentationWriters sometimes create an antecedent problem when they use the word “using,” as in the following examples:

Exporting Data Using the Export Logs Option [Sounds like it is the data that is using the option] The default configuration starts all J2EE services using the JBoss optimized class loader.

[Sounds like the services are using the loader.] Requiring each web server to protect data using SSL can significantly reduce the web server’s

performance. [Sounds like the data is using SSL.] Web servers can be encrypted over the network using a single SSL certificate. [Sounds like the

network is using the certificate.] Users must be enabled using Linux User Management. [Ambiguous. Are the users using Linux

User Management, or do you use it to enable them?] GWCheck creates the user in ngwguard.db using the database userabc.db.[Sounds like

nwguard.db is using the database.]

The easiest way to remedy the problem is to insert the word “by” in front of “using:”

You can also revise the word order of the sentence or heading:

When you revise the word order in a heading, ensure that it stays parallel with wording in other headings at the same level.

In some cases, simply using a comma provides the needed separation:

Occasionally, you can use the word “through” or “with” instead of the word “by” to clarify meaning:

Chicago discusses the issue in its Q and A section:

Q. I’m reviewing a scientific manuscript in which the copyeditor has changed every instance of “using” to “by using”—for instance, “describe a vector by using Cartesian coordinates.” I can find no usage manual that comments on “using” versus “by using,” and other people’s opinions seem to be split. Does “using” require a “by”?

A. If “using” can be misread as “that/who is using,” then it is a good idea to add “by”:

Example: The default configuration starts all J2EE services by using the JBoss optimized class loader.

Example: Requiring each web server to protect data by using SSL can significantly reduce the web server’s performance.

Example: Using the Export Logs Option to Export Data

Example: You can use a single SSL certificate to encrypt web servers over the network.

Example: DBCOPY prevents the files from being modified, using the same locking mechanism used by other GroupWise programs.

Example: GWCheck creates the user in ngwguard.db, using database userabc.db.

Example: Users must be enabled through Linux User Management.

Example: GroupWise is administered with ConsoleOne,


The MMoS, 4th Edition, also has a recommendation: “To help the worldwide audience and to reduce the possibility of ambiguity that makes localization more difficult, use by using instead of using, even if the preposition seems unnecessary.”

B.9 Verb TenseWe see occasional verb tense problems as we edit documentation, mostly with incorrect usage of the future tense. Here’s a review of the Style Guide guidelines and examples, along with some additional examples.

Use the simple present tense almost exclusively.

Unless there is a very clear shift in time from past to present or a very clear reference to the future, describe a series of actions in the present tense.

State perpetual cause-and-effect relationships (every time x happens, y occurs) in the present tense.

Wrong: Describe a child using a pen.

Wrong: Describe a child who is using a pen.

Right: Describe a child by using a pen.

Wrong: The password contained an invalid character.

Right: The password contains an invalid character.

Wrong: Installing this service pack will update the product to the same version that is on the CD.

Right: Installing this service pack updates the product to the same version that is on the CD.

Wrong: This will ensure that all Distributors and Subscribers will work correctly together.

Right: This ensures that all Distributors and Subscribers work correctly together.

Wrong: The order would be shown by the PackageList command.

Right: The order is shown by the PackageList command.

Wrong: When you select this command, GroupWise will open the text files.

Right: When you select this command, GroupWise opens the text files.

Wrong: You will now be able to discover the switches with their corresponding interfaces.

Right: You can now discover the switches with their corresponding interfaces.


Use future tense only when anticipating an event that is yet to happen.

B.10 CPU vs. Processor Use CPU when you refer to the CPU itself.

Use processor when you present more general information.

B.11 RAM vs. Memory Use RAM when you outline specific requirements for the computer’s active operational memory.

Use memory when you present more general information about the computer’s active operational memory.

Wrong: The Publish operations do not work with eDirectory 8.6.22. You will need to upgrade to eDirectory 8.7.

Right: The Publish operations do not work with eDirectory 8.6.22. You need to upgrade to eDirectory 8.7.

Wrong: If they are running, these processes will hold open a number of files.

Right: If they are running, these processes hold open a number of files.

Wrong: If you want to roll back Package 2, you will need to first roll back Package 1.

Right: If you want to roll back Package 2, you need to first roll back Package 1.

Example: In the next lesson, you will learn how to write a macro.

Example: After you finish this lesson, you will know how to write macros.

Example: 3GHz x64 CPU

Example: dual-core CPU

Example: 64-bit architecture processor

Example: at least 8 GB RAM

Example: 2 GB RAM (64-bit)

Example: Memory allocation is proportional to the index size.


C CProject Style Sheet Example

Create a Project Style Sheet to document the project-specific terminology and abbreviations that are common to users of your specific product or technologies. Information developers should refer to these guidelines to ensure consistency in usage and spelling across deliverables.

Table C-1 provides an example of project-specific terminology for the CloudAccess product documentation.

For mixed-case words and abbreviations, preserve the mix of lowercase and uppercase letters in running text and headings, unless the heading is in all capitals.

For abbreviations and acronyms, use articles “a” or “an” based on the pronunciation of the first letter or the word, such as “an SNMP agent” (pronounced letter-by-letter “ess-en-em-pee” with an initial vowel sound) or “a RAID device” (pronounced as a word “raid” with an initial consonant sound).

Table C-1 CloudAccess Terminology Guidelines

Word or Phrase Usage Guidelines

appmark Noun: One word, no hyphen.

A single sign-on link to a web-based application.

IDaaS Acronym for Identity as a Service. Pronounced “eye-daz”.

An identity and access management service that is offered through the cloud.

JavaServer Pages Proper noun.

A server-side programming technology.

JSP Abbreviation for JavaServer Pages. Pronounced “J-S-P”.

A file name extension for JavaServer Pages file format.

KitKat Proper noun.

A distribution of Android.

NIC Acronym for Network Interface Card. Pronounced “nick”. Use “NIC” instead of “adapter”.

Plural: NICs. Pronounced “nicks”.

OAuth Proper noun. Pronounced “oh-auth”.

An open standard for authorization.

OVF Abbreviation for Open Virtualization Format. Pronounced “O-V-F”.

A file name extension for the OVF file format. OFV is an open standard for packaging and distributing virtual appliances.

Project Style Sheet Example 273

reCAPTCHA Proper noun. Pronounced “re-KAPT-chuh”.

A multi-factor authentication tool from Google used to help distinguish human from machine input.

SaaS Acronym for Software as a Service. Pronounced “sass”.

A software distribution model in which a third-party provider hosts applications and makes them available to customers over the Internet.

Salesforce Proper noun.

A third-party vendor.

sign-on

sign on

Noun or adjective: One word, hyphenated.

Verb: Two words.

SPNEGO Acronym for Simple and Protected GSS-API Negotiation Mechanism. Pronounced “spen-go”.

A mechanism used by client-server software to negotiate the choice of security technology.

SSO Abbreviation for single sign-on. Pronounced “S-S-O”.

WebEx Proper noun.

An online meeting and video conferencing product from Cisco.

WS-Fed Acronym for WS-Federation (Web Services Federation). Pronounced “W-S-fed”.

An Identity Federation specification that defines mechanisms for allowing different security realms to broker information on identities, identity attributes, and authentication.

YubiKey Proper noun. Pronounced “yoo-bee-key”.

A USB authentication key product from Yubico.

Yubico Proper noun. Pronounced “yoo-bee-co”.


Zoho Proper noun. Pronounced “zoh-hoh”.


Word or Phrase Usage Guidelines

274 Project Style Sheet Example

D DProduct Terminology

For heritage products, follow the spelling, spacing, hyphenation, and case guidelines of these product-specific terms.

Section D.1, “Heritage Micro Focus Product Terminology,” on page 275 Section D.2, “Heritage Novell Product Terminology,” on page 281

D.1 Heritage Micro Focus Product TerminologyFor heritage Micro Focus products, follow the spelling, spacing, hyphenation, and case guidelines for these product-specific terms.

For terminology guidelines that apply to all products, see Chapter 3, “Word Choice and Usage,” on page 75.

D.1.1 AAccess Control Block action bands (instead of ActionBands) AddPack Analyzer Animator Application Configuration System AppMaster Builder AppTrack ANSI'74 ANSI'85 Assembler AssetMiner autosave

D.1.2 BB2B messaging Base Class Library Banner program basename Batch File Facility

A B C D E F G H I J

K L M N O P Q R S T

U V W X Y Z

Product Terminology 275

Btrieve Interface Build Utility bytecode

D.1.3 CCaliberRDM CaliberRM Callable File Handler Callable Sort Module CICS (Customer Information Control System) CICS option CLIST (command List) CLOB (Character Large Object) Co-Graphics Co-Maps Co-Math Co-Reports Co-Writer Co-Writer Builder Co-Writer Designer Co-Writer Reporter cob command COBOL (Common Business-Oriented Language) COBOL Communication Module COBOL Editor COBOL Source Information COBOL System Library Routines COBOL Workbench codebase code-behind (files) code page Color Utility Compiler (when referring to the Micro Focus one), compiler (when referring to other compilers) Compiler Dictionary Interface Component Generator compound key Concurrent COBOL Environment Configuration System control block Convert3 Convert5 copybook (not copyfile) copylibrary CRM (Customer Relationship Management) crosshair crosstab

276 Product Terminology

CSECT (Control Section)

D.1.4 DData File Editor DataConnect dataflow dataset datasheet DB2 DBA (Database Administrator) DBCS (Double-Byte Character Set) DBMS (Database Management System) DBMS connector DDIO (Dump Datasets Input Output) ddname DD name DD statement DDL (Data Definition Language) Demonstration Programs Dialect Compatibility Tools Dialog System Dimensions Agent Directory Facility DL/I (Data Language 1) DOM (Document Object Model) DSECT (Dummy Control Section) DSN (Data Set Name)

D.1.5 EEBCDID (Extended Binary Coded Decimal interchange Code) ECC (Enterprise Common Components) EJB (Enterprise JavaBean) Enhanced Accept/Display EnterpriseLink ESV subtype EuroSmart External File Mapper

D.1.6 FFile Finder File Handler File Handler utilities Fileshare Version 2 Fileshare View and Administration Tool


Fileshare View and Administration Tool (GUI) File Specification and Directory facility File Transfer Aid File Transfer Aid (GUI) FixPack Floating Point Handler Forms Forms-2

D.1.7 GGeneral Assembly Cache (GAC)

D.1.8 HHCI (Host Communications Interface) Header-to-Copy utility Hex Edit utility HLLAPI Interface

D.1.9 IIMS (Information Management System) IMS Option includefile Installation Program Indexed File Maintenance Tool Integrated Preprocessor Interface IRMA Interface

D.1.10 JNone.

D.1.11 KKeyboard Configuration utility Keystroke Macro utility

D.1.12 LLEVEL II COBOL Library utility License Server line sequential Linein program linefeed


lineup (n) Linking Support LMS (License Management System) LP (Language Processor) LRECL (Logical Record Length)

D.1.13 MMainframe Access Mainframe Development Environment Mainframe Express Mainframe Manager MAPI (Message Application Program Interface) Memsnap Menu Handler Micro Focus 370 Assembler modal form Multi-thread EnvironmentMVS (Multiple Virtual Storage)

D.1.14 NNet Express

D.1.15 OObject COBOL Object COBOL Developer's Suite OCDS Online Reference online transaction processing OpenESQL

D.1.16 PPanels Panels Version 2 Parameter Passer PDS (Partitioned Data Set) Personal COBOL Professional COBOL PF key Probe Profiler


D.1.17 QQt (the Trolltech library on which CLX is based)

D.1.18 RRACF (Resource Access Control Facility) Remote IMS REQL Revolve Revolve TPS RTE

D.1.19 SScreen Configuration utility screensetScreen Painter Server Express Session Recorder SilkCentral Test Manager SilkPerformer SilkPerformer CloudBurst SilkPerfromer Diagnostics SilkTest SmartFind SmartFind Plus SmartFix SMF (System Management Facilities) Snapshot File Analyzer Sort utility Source Converter Source File Comparison utility SourceConnect SourceWriter SQL Database support StarTeam static linked run-time system

D.1.20 Tthird-generation programming language (3GL) Toolbox

D.1.21 UNone.


D.1.22 VVBA (Visual Basic for Applications) VBScript Visual Basic VS COBOL VSAM (Virtual Storage Access Method)

D.1.23 WNone.

D.1.24 XXilerator XM

D.1.25 YNone.

D.1.26 ZNone.

D.2 Heritage Novell Product TerminologyFor heritage Novell products NetWare and NetWare services ported to Open Enterprise Server, follow the spelling, spacing, hyphenation, and case guidelines for these product-specific terms.

For terminology guidelines that apply to all products, see Chapter 3, “Word Choice and Usage,” on page 75.

Section D.2.1, “Open Enterprise Server and NetWare Terminology,” on page 281 Section D.2.2, “Properties, Attributes, Objects, and Rights,” on page 284

D.2.1 Open Enterprise Server and NetWare Terminology


abnormal end In the NetWare operating system, use “abend” instead.

Access rightaccess right

As a NetWare right, this term is capitalized. Do not, however, confuse this term with the GroupWise term “access right” (lowercased), which is an assignment allowing an alternate user to access someone’s mailbox as a proxy.


Account Balance property

account balance

When this phrase appears as a selectable property right or as a Directory schema term in English, the first letters of each word are capitalized. After the first occurrence of this term in any discussion, the word “property” can be dropped. The capitalization of the remaining words remains unchanged. When it is a value assigned by a NetWare network administrator to limit the amount of network services a user can use, it is lowercase.

See “Properties” on page 284 for information about using property names.

Accounting Capitalized when it refers to the NetWare feature.

active connections Capitalize this term only when it refers to the name of the screen.

ADMIN When it refers to the NDS User object ADMIN, this term should be presented in all capitals.

administrative privilege This term appears in a software system message. However, use “administrative rights” in documentation.

afp module Use afp.nlm instead.

attach Use “establish a connection” instead.

attribute In the NetWare file system, any of the characteristics assigned to directories and files that dictate what can be done with the directories or files, such as Archive Needed (A).

On first occurrence in a discussion, use the full term, such as “Cannot Compress attribute.” On subsequent occurrences, the word “attribute” can be dropped. The capitalization of the remaining words remains unchanged.

See “Attributes” on page 285 for a list of attribute names.

Do not use “attribute” as a synonym for “property.”

Auditor container login Follow this capitalization when it is used as a menu option in the AUDITCON utility.

authenticate In Novell user interface design, using this term is discouraged.

Backup Restore Agent: The full term is “Directory Services Backup Restore Agent.” “Backup Restore Agent” is not used alone.

balance beam policy This Motif 1.2 term (in the Common Desktop Environment) is no longer used. The preferred term is the Motif 2.0 term “midpoint technique.”

bindery emulation Do not use.

BMenu Do not use in the user interface or user documentation (restriction applies to the Common Desktop Environment).

BSelect Do not use in the user interface or end-user documentation where Selection button and button 1 are the acceptable terms.

BTransfer Do not use in the user interface or end-user documentation where Transfer and mouse button 2 are the acceptable terms.

button bar The term “toolbar” is preferred. Button Bar (with initial capitalization) is a trademark of Corel Corporation.



Call Request packet Use capitalization as shown (do not present in lowercase).

Coach Outdated term for an interactive tutor-style help option in GroupWise.

Configuration Manager Short for Novell Configuration Manager. Upon its first occurrence in any discussion, use the full term. Thereafter the word “Novell” can be dropped.

Configuration Manager Console

Short for Novell Configuration Manager Console. Upon its first occurrence in any discussion, use the full term. Thereafter the word “Novell” can be dropped.

connection-oriented Note hyphen when used to refer to SPX communication between dedicated nodes.

container login script Do not use “system login script” as a synonym for this term. (Novell Client)

controlled access printer

Controlled Access Printer was a trademark of Novell, Inc. In early 1998 the trademark attribution was removed; this term should be presented in lowercase.

Designated Router Use initial capitals when you are discussing routers in NLSP.

entry box In the NetWare interface, a box that lets the user enter information (such as a directory path) needed to accomplish a task.

Example: Type the path to the correct drive in the Path entry box.

Expert Recommended for Novell user interface design instead of “Advisor” for a Help feature in which the computer performs the action with little or no help from the user. For example, “Upgrade Expert,” not “Transition Advisor.”

form In NetWare, a box that contains fields in which the user enters information. Some fields have menus the user can access from the form.

Example: The utility displays the Add New Server form when you press Enter.

ITRN Avoid using this abbreviation for IMB Token-Ring Network.

LWP Avoid using this abbreviation for LAN WorkPlace

NetWare Remote Manager

Outdated. Use “Novell Remote Manager instead.”

See also Novell Remote Manager.

Novell Remote Manager

Do not use “NORM” to refer to the Novell Remote Manager utility. “NRM” is acceptable if an acronym is necessary, but the full product name is best. (Engineers often pronounce it “Norm,” which is probably where the incorrect acronym comes from.)

property A category of information stored within, and pertaining to, Directory objects.

On first occurrence in a discussion, use the full term, such as “Full Name property.” On subsequent occurrences, the word “property” can be dropped. The capitalization of the remaining words remains unchanged.

See also attribute.

See “Properties” on page 284 for a list of specific NetWare property names.

Readme / readme In an environment that is not case sensitive, use the spelling “Readme” when you refer generically to “the Readme file,” and use all lowercase when you refer to a readme.txt or readme.htm file. In a case-sensitive environment, match the file name spelling for specific files and use the most common form for generic references.



D.2.2 Properties, Attributes, Objects, and RightsFollow these guidelines for terminology used in NetWare and for NetWare services ported to Open Enterprise Server.

“Properties” on page 284 “Attributes” on page 285 “Objects” on page 286 “Schema Terms” on page 287 “Rights” on page 289

PropertiesUpon the first occurrence in any discussion, use the full term. Thereafter, the word “property” can be dropped.

Account Balance propertyAccount Has Expiration Date propertyAccount Locked propertyAccount Reset Time propertyAliased Object propertyAllow Unlimited Credit propertyAllow User to Change Password propertyCity propertyDate Password Expires propertyDays Between Forced Changes propertyDefault/Host Server propertyDepartment propertyDescription propertyFax Number propertyFull Name propertyGenerational Qualifier propertyGiven Name property

rights A permissions assignment that allows access to or manipulation of a resource in some way; for example, browse, read/write, or create.

On first occurrence in a discussion, use the full term, such as “Access right.” On subsequent occurrences, the word “right” can be dropped. The capitalization of the remaining words remains unchanged.

See “Rights” on page 289 for more information about names for rights.

SET parameter All capitals.

Support Packsupport pack

Use initial capitals when you refer to a specific support pack, and use lowercase when it is generic.

Example: Download Support Pack 5.Example: You can download different support packs.



Grace Logins Allowed propertyHome Directory propertyHost Volume propertyLanguage propertyLast Name propertyLocation propertyLogin Script propertyLow Balance Limit propertyMailing Label Information propertyMaximum Connections propertyMembers of Template propertyMiddle Initial propertyMinimum Password Length propertyName propertyNetwork Address propertyObject Trustees propertyOrganization propertyPostal (ZIP) Code propertyPost Office Box propertyProfile propertyRequire a Password propertyRequire Unique Passwords propertyResource propertyRun Setup Script propertySecurity Equal To propertySecurity Equal To Me propertySee Also propertySerial Number propertySet Password After Create propertyState or Province propertyStatusStreet propertySupported Connections propertySupported Services propertyTelephone propertyTitle propertyUsers propertyVersion propertyVolume Space RestrictionsWorkstation Class

AttributesUse the following capitalization for NSS file system attributes. Upon its first occurrence in any discussion, use the full term. Thereafter, the word “attribute” can be dropped.

Archive Needed attributeCannot Compress attribute


Compressed attribute (Use instead of “Compress attribute”)Copy Inhibit attributeDelete Inhibit attributeDon’t Compress attributeDon’t Migrate attributeDon’t Suballocate attributeExecute Only attributeHidden attributeImmediate Compress attributeIndexed attributeMigrated attributeNormal attributePurge attributeRead-only attributeRead Write attributeRename Inhibit attributeShareable attributeSystem attributeTransactional attribute

ObjectsUse the following capitalization for directory objects. Upon its first occurrence in any discussion, use the full term. Thereafter the word “object” can be dropped.

Account Locked objectAccount Reset Time objectACL objectAFP Server objectAlias objectAliased Object Name objectAll Properties Rights objectAudit File objectAuthority RevocationBindery objectBroker objectComputer objectconsumer object. Note lowercase. container object. Note lowercase.Country objectDirectory Map objectDistribution List objectExternal Entity objectGroup objectleaf objectLicense objectLicense Certificate objectLocality object


LSP Server objectMessage Routing Group objectMessaging Server objectNDPS Manager objectNetWare Server objectOrganization objectOrganizational Role objectOrganizational Unit objectPrinter objectPrint Queue objectPrint Server objectProfile objectTemplate objectUser objectVolume object

Schema TermsThe NTM calls the following terms “Directory Schema terms” and indicates that they should be capitalized when they are used as such. In other usages, they might not be capitalized.

Back LinkBindery Object RestrictionBindery PropertyBindery TypeCA Private KeyCA Public KeyCartridgeCertificate RevocationCertificate Validity IntervalCNComputerConfigurationConvergenceCross Certificate PairDefault QueueDetect IntruderDirectory MapDS RevisionEmail Address: Note special capitalization and lack of hyphen.Equivalent To MeExternal SynchronizerForeign Email AliasGIDHigh Convergence Sync IntervalHigher PrivilegesHome DirectoryHost Resource Name


Host ServerIncorrect Login AttemptIncorrect Login CountIntruder Attempt Reset IntervalLanguageLast Intruder AddressLast Login TimeLast Referenced TimeLock Account After DetectionLogin ScriptLogin TimeLogin Time RestrictionsLow Convergence Reset TimeLow Convergence Sync IntervalMailbox IDMailbox LocationMemberMessaging Database LocationMessaging Server TypeNCP ServerNetwork AddressNetwork Address RestrictionObject ClassOrganization NameOrganizational PersonOther NamesPartition ControlPartition Creation TimePasswords UsedPersonPhysical Delivery Office NamePost Office BoxPostmasterPrinterPrinter ConfigurationPrinter ControlPrint QueuePrint ServerPrivate KeyProfilePublic KeyQueueQueue DirectoryRead Up ToRemaining Grace LoginsReplica Up ToRequire Unique Passwords


ResourceevisionSSAP NameSecurity EqualsSecurity FlagsSee AlsoServerServer HoldsSkipState or ProvinceStatusStreet AddressSupported GatewaySupported TypefacesSurnameSynchronization IntervalSynchronized Up ToTelephone NumberTransaction SetType Creator MapUIDUnknownUnknown Base ClassUnknown Object RestrictionUserVolumeVolume Restrictions

RightsUse the following capitalization for file access rights for the NetWare and NSS file systems. Upon its first occurrence in any discussion, use the full term. Thereafter the word “right” can be dropped. In other products, these terms might not be capitalized.

Access rightAll Properties rightsCompare right: This term should usually be accompanied by the word “right” to make it clearCreate rightdefault rights: Note capitalization.Erase rightFile Scan rightModify rightobject right: Note capitalization.Read rightSupervisor rightWrite right



E EDocumentation Updates

This section identifies changes to the Micro Focus Style Guide since the integrated style document was released in September 2017.

Section E.1, “May 2018,” on page 291 Section E.2, “November 2017,” on page 291

E.1 May 2018

E.2 November 2017

Location

Section 17.6, “Video Editing and Post-Production Services,” on page 231

Added James Aguilar as a video post-production resource.

Removed Russ Dastrup and Stephanie Wilson as video post-production resources.

Section 17.7, “Video Publication on YouTube,” on page 231

You must submit video publication requests to Marketing Services through the Micro Focus portal for WorkFront (https://microfocus.my.workfront.com). See this section for information about getting a WorkFront account and instructions for submitting a request.

Location

Section 17.6, “Video Editing and Post-Production Services,” on page 231

Added Greg Posten and Stephanie Wisdom as video post-production resources.

Removed Luke Filar as a video post-production resource.

Documentation Updates 291



292 Documentation Updates