book

Read Me First!: A Style Guide for the Computer Industry, Second Edition

by Sun Technical Publications

May 2003

Beginner

384 pages

6h 22m

English

Pearson

Read now

Unlock full access

How This Book Is OrganizedChanges for This RevisionAcknowledgments
CapitalizationWhat to CapitalizeWhat Not to CapitalizeContractionsGerunds and ParticiplesNumbers and NumeralsSpelling Out NumbersUsing NumeralsPunctuating Numbers and NumeralsUsing FractionsPronounsTechnical Abbreviations, Acronyms, and Units of MeasurementAbbreviations and AcronymsBasic Guidelines for Abbreviations and AcronymsPunctuating Abbreviations and AcronymsUnits of MeasurementPunctuationApostropheBracketsColonWhen to Use a ColonWhen Not to Use a ColonCommaWhen to Use a CommaWhen Not to Use a CommaDash (Em Dash)Dash (En Dash)Ellipsis PointsExclamation PointHyphenWhen to Use a HyphenWhen Not to Use a HyphenParenthesesWhen to Use ParenthesesPeriodQuotation MarksSemicolonSlash
HeadingsWriting Section HeadingsUsing Fonts in HeadingsCapitalizing and Punctuating HeadingsNumbering Section HeadingsListsIntroducing ListsList Introduction GuidelinesList Introductions and VerbsCapitalizing and Punctuating ListsWriting Bulleted ListsWriting Numbered ListsWriting Jump ListsTablesWriting Text for TablesTable IntroductionsTable CaptionsTable Column HeadingsTable TextDetermining the Type of Table to UseCode ExamplesError MessagesCross-ReferencesFormatting Cross-ReferencesWriting Cross-ReferencesEndnotes, Footnotes, and BibliographiesWriting Endnotes and FootnotesWriting BibliographiesCiting BooksCiting ArticlesFormatting BibliographiesCiting Electronic SourcesFormatting Electronic SourcesNotes, Cautions, and TipsWriting NotesWriting CautionsWriting TipsPart DividersTypographic ConventionsKey Name ConventionsReferring to KeysDocumenting Multiple Keystrokes
Why Is Style Important?Stylistic PrinciplesWrite Simply, Directly, and AccuratelyBe ConsistentSome Basic Elements of StyleAvoid JargonUse Active Voice and Passive Voice AppropriatelyUse Present Tense and Future Tense AppropriatelyUse Sentence Structures That Enhance UnderstandingAvoid Complex, Conjoined SentencesSeparate Independent Clauses AppropriatelyLimit Subordinate ClausesUse Positive ConstructionsUse Parallel StructureDifferentiate Between Restrictive Clauses and Nonrestrictive ClausesWrite Concise ParagraphsWriting for the ReaderMake Decisions for the ReaderAnticipate the Reader’s QuestionsAnticipate QuestionsUse Cross-References to Address Anticipated QuestionsStyle That Could Offend the ReaderAvoid HumorAvoid Sexist LanguageUse Acceptable Methods to Achieve Common GenderAvoid Unacceptable Methods to Achieve Common GenderRespect the ReaderCommon Writing Problems to AvoidAnthropomorphismsCommands as VerbsRedundanciesWays to Improve Your StyleStudy Good WritingWork With an EditorAttend Classes and Training
About These GuidelinesSolving Online Writing ProblemsCreating an Effective Document StructureUse an Easy-to-Follow, Meaningful StructureOrganize Text by HierarchyOrganize Text by Inverted PyramidOrganize Text by TableOrganize Text by Flow DiagramOrganize Text by Task MapWriting Short, Self-Contained TopicsDivide Text Into Self-Contained, Linked TopicsFocus on the Structure of ContentConstructing Scannable Paragraphs, Headings, and ListsWrite Clearly and SimplyKeep Paragraphs ShortEliminate Unnecessary MaterialCondense Text CarefullyWrite Meaningful Headings and SubheadingsUse Bulleted ListsUse Jump ListsPreserving Context in Online DocumentsMake Few Assumptions About Reading OrderOffer Contextual CuesGive the Precise Location of Related Information
About These GuidelinesWhere to Place LinksGeneral Linking StrategiesAvoid OverlinkingAvoid Interrupting ReadersDo Not Link the Same Text RepeatedlyMinimize the Number of ClicksLimit Internal LinkingPrevent Reader DisorientationInclude Links That Answer the Reader’s QuestionsUse Links to Make Text Seem ShorterProvide Links in a ListPlace Links at the End of a TopicProvide URLs Only When NeededTest the Validity of LinksGuidelines for Writing Link TextProvide Context in Link Text and Surrounding TextWeave Link Text Into Sentence StructureChoose Key Words or Phrases for Link TextChoose an Appropriate Length for Link TextWrite Scannable Link TextMake Link Text Conceptually Similar to Titles or HeadingsDo Not Use Quotation Marks Around Link Text
Understanding the Relationship Among Tasks, Procedures, and StepsDeveloping Task InformationPerform an Audience Analysis and a User Task AnalysisProvide Only Necessary InformationIncluding PrerequisitesProviding ExamplesOrganize Related, Optional, and Conditional TasksUsing Jump Lists to Organize TasksUsing Task Maps to Organize TasksUsing Flow Diagrams to Organize TasksUse Continuous ProseWriting ProceduresWrite Procedures That Are Easy to FollowPlace Procedures AppropriatelyUse Procedure Headings AppropriatelyUse One Method in a Single ProcedureWriting StepsNumber the StepsMake Each Step Short and Equivalent to One ActionWrite Each Step as a Complete SentenceWrite Meaningful StepsUse Branching of Steps AppropriatelySigns of Structural ProblemsDuplicate Sets of StepsNearly Identical ProceduresProcedures With More Than 10 StepsSeveral Single-Step Procedures

General Guidelines for Writing for TranslationCultural and Geographic SensitivityUse Culturally Neutral ExamplesInclude International Date, Time, and Contact InformationAvoid Informal Language and StylesDefinitions and Word ChoiceAvoid Jargon and SlangUse Terms ConsistentlyAvoid Abbreviations, Acronyms, and ContractionsGrammar and Word UsageFollow These Grammar GuidelinesUse Words PreciselyUse Modifiers and Nouns CarefullyLimit the Use of PronounsSimplify SentencesNumbers, Symbols, and PunctuationClarify Measurements and DenominationsAvoid Certain Symbols and Punctuation MarksIllustrations and Screen CapturesChoose Illustrations to Communicate InternationallyCreate Callouts That Are Easy to TranslateUse Charts and TablesUse International Illustrations, Symbols, and Examples
CopyrightsGeneral Copyright InformationCopyright DurationCopyright RegistrationCopyright Compared With a Trade SecretWhat Should You Copyright?Copyright NoticeCopyright Date for a Revised DocumentThird-Party Copyrighted InformationTrademarksTrademark TermsProper Use of TrademarksTrademark SymbolsTrademark Symbol PlacementTrademark UsageTrademarks and Appropriate NounsProper Use of Third-Party TrademarksThird-Party Web Site ReferencesDetermining Which Third-Party Site to ReferenceDetermining Which Third-Party URL to UseAdding a Disclaimer and Required Third-Party WordingPreventing Unapproved References to Third-Party SitesProtection of Proprietary/Confidential InformationIdentifying Proprietary/Confidential InformationProtecting Proprietary/Confidential DocumentsProtecting Electronic CommunicationProtecting Information That Appears in Examples
What Is a Documentation Set?Documentation PlansDocumentation Set PlanDocumentation Set Plan TemplateDocumentation Set Revision Plan TemplateDocument PlanDocument Plan TemplateDocument Revision Plan TemplateAbstractsStructure of ManualsManuals With a Single ChapterManuals With Multiple ChaptersDescriptions of the Manual PartsTitle PageLegal NoticeTable of ContentsList of FiguresList of TablesList of ExamplesPrefaceChaptersPart DividersAppendixesGlossaryBibliographyIndexTypes of Hardware ManualsInstallation GuidesSystem Overview GuidesUser’s GuidesService ManualsConfiguration GuidesTypes of Software ManualsInstallation GuidesProgrammer’s GuidesSystem Administration GuidesUser’s GuidesReference GuidesOther Product DocumentsWhite PapersOnline HelpCD TextCD Faceplate TextCD Text InsertRelease Notes and Product NotesDemosTraining DocumentsStudent Guides and Instructor GuidesOther Training Documents
Technical Editor’s RoleEditor’s Role in Producing Online DocumentsTypes of EditingDevelopmental EditingDevelopmental Editing ChecklistStructure and OrganizationWritingStyleFormatting and LayoutIllustrationsNew ElementsCopy EditingCopy Editing ChecklistReadabilityStyleTransitionsGrammarPunctuation, Capitalization, and SpellingMechanicsFormatting and LayoutIllustrationsProofreadingProofreading ChecklistFront MatterBack MatterGrammarPunctuation, Capitalization, and SpellingMechanicsFormatting and LayoutIllustrationsEdit SchedulesDocument SubmissionEditing MarksEdit Style SheetEditorial Style Sheet
Working With an IllustratorIllustration Standards and ProcessesWhen to Contact an IllustratorSubmitting an Illustration RequestIllustration Formats, Styles, and TypesIllustration FormatsVector GraphicsRaster ImagesIllustration StylesIllustration TypesExamples of IllustrationsDiagramsOnline GraphicsLine ArtScreen CapturesCompositesPhotographs2–D AnimationsWeb AnimationsPlacing IllustrationsPlacement in Relation to SentencesSpacing in PrintAlignment in PrintOnline Alignment and SpacingWriting Captions for IllustrationsWhen to Use CaptionsGuidelines for Writing CaptionsWriting Callouts for IllustrationsCallout StylePlacement of CalloutsCreating Quality Screen CapturesGuidelines for Creating Screen CapturesUsing Screen Captures as Guideposts OnlyCreating Leader LinesLeader StyleAdditional GuidelinesSimplifying Online Illustrations
Using GUI TerminologyWriting About GUIsWriting About Mouse ActionsUsing Common GUI VerbsWriting About Windows, Dialog Boxes, and MenusWindow ElementsWindow ControlsDialog BoxesMenusWriting About the WebWeb TerminologyReferencing URLs
Glossary ContentFinding DefinitionsCreating New TermsFormatting a GlossaryTerms for an International AudienceWhen to Include a GlossaryWriting Good Glossary EntriesIntroducing Glossary Entries in TextWording a Glossary EntryWording the DefinitionDefining Multiword TermsDefining Parts of SpeechCreating Multiple DefinitionsDefining Acronyms and AbbreviationsUsing “See” and “See Also” ReferencesAlphabetizing a GlossaryCreating Online LinksIndexing Glossary Terms
What Is an Index?Style and FormatNested EntriesPage Number StyleMajor Page ReferencesPage RangesSpecial Typography“See” and “See Also” ReferencesCapitalizationPunctuationCreating an IndexTime Required to Create an IndexDeciding Which Parts of a Document to IndexSelecting Topics to IndexDo Not Index Superfluous EntriesAvoid Entries That Are Too GeneralInclude Common Industry TerminologyAvoid Using Headings as Index EntriesConsider Including “Commands” as a Primary EntryDescribing a TopicAnticipate a Reader’s NeedsInclude Only Terms a Reader Is Likely to Look UpSelect Proper Words for SubjectsUse GerundsIdentify the Entry TypeArrange Words for EmphasisUse Plural for Main EntriesAssign the Proper Font to the EntryGroup EntriesCreate Index Entries for Cautions, Notes, and TipsCreate Index Entries for Acronyms and AbbreviationsDouble-Posting EntriesCreating “See” and “See Also” ReferencesWhen to Use “See” and “See Also” ReferencesHow to Use “See” and “See Also” ReferencesAvoiding Indexing ProblemsUse a Single-Level Entry for a Single TopicUse an Adjective With a Noun as a Primary EntryAvoid a Primary Entry That Is Too GeneralDo Not Over-IndexDo Not Under-IndexAlphabetize by Keyword in SubentriesAlphabetize by First Letter After a SymbolRefining and Checking an IndexSpellingDifferences in WordingMisused Singular Forms and Plural FormsEffective Double-PostingNumber of Page References for EntriesProper Topic Cross-References“See” and “See Also” ReferencesBad Page and Column BreaksSecondary EntriesLevels of Secondary EntriesRedundant Secondary EntriesPossible Primary Entries in Secondary EntriesPossible RearrangementAppropriately Combined Secondary EntriesSecondary Entries Under More Than One TopicSecondary Entries When Using a Combined Term SeparatelySecondary Entries Under Various Forms of One TopicChecking the Size of the IndexGlobal IndexFormatting a Global IndexEditing a Global IndexOnline Index
Establishment of a Publications DepartmentEstablishing the Value of the DepartmentAccounting for Value AddedTracking Avoided Costs and Costs SavedEstablishing ExpertiseFunding the Publications DepartmentDetermining the Roles of the Publications TeamManagerWriting Team LeaderWriterEditorGraphic DesignerIllustratorDeciding on Contract or Permanent StaffAdvantages of Using ContractorsDisadvantages of Using ContractorsConsiderations When Hiring ContractorsConsiderations When Hiring Permanent StaffSchedulingEstimating Task TimesDeveloping a Project ScheduleDocumentation ProcessWriting a Documentation PlanCoordinating With Product DevelopmentWriting ProcessFirst DraftSecond DraftEditing ProcessIllustration and Graphics DesignIllustration ConcernsGraphics Design ProcessTechnical ReviewComment AcceptanceParticipants in the Technical ReviewReview MeetingInternationalization and LocalizationOnline Documentation ConsiderationsWriting IssuesContent IssuesManagement IssuesFinal Print ProductionDeciding on a StrategyPrinting MethodsOffset PrintingPhotocopyingBinding MethodsThree-Ring BindersWire-OPerfectSaddle-StitchPackagingWorking With Outside VendorsPost-Production ConsiderationsHandling Post-Production RevisionsMaintaining Project Continuity
Manuscript Tracking ChartRequest for Editing FormArtwork Request FormTechnical Review Cover LetterAuthorization to Produce DocumentPrint Specification

Content preview from Read Me First!: A Style Guide for the Computer Industry, Second Edition

Chapter 13. Glossary Guidelines

This chapter explains how to create a glossary for a technical manual. Most technical manuals increasingly introduce a number of new terms. A glossary improves the usability of a technical manual by simplifying a reader’s search for definitions for these new terms. Before you create a glossary, consider its use and organization.

This chapter discusses the following topics:

“Glossary Content” on page 231
“Terms for an International Audience” on page 233
“When to Include a Glossary” on page 234
“Writing Good Glossary Entries” on page 234

Glossary Content

The terms that you select for a glossary must be important to the subject, with simple and concise definitions that are appropriate for the context. A glossary can contain ...