• GNOME-STYLE

GNOME Documentation Style Guide V1.6

Preface

The GNOME Documentation Style Guide provides guidelines for authors who want to contribute to the GNOME Documentation Project (GDP).

1. About This Guide

The goal of the GNOME Documentation Style Guide (GDSG) is to provide a framework for contributors to write good documentation. The GDSG also helps authors to write consistent documentation, so that users can expect certain structures and conventions in GNOME documents.

This style guide discusses basic principles of clear, concise writing so that users can achieve the maximum benefit from GNOME documentation. The guide also provides standards for common terms and concepts. The guide provides recommendations rather than absolute rules. However, in all parts of the user interface, including documentation, consistency is a virtue. When you write GNOME documentation, try to follow these guidelines as closely as possible. Users benefit from the consistent application of the guidelines in this guide.

This style guide is primarily for authors contributing documentation to the GDP in English. Although you can apply many of the guidelines in this book to all languages, there some guidelines that are specifically for English-language usage.

2. What Is in This Guide

This guide contains the following sections:

Section Summary
Chapter 1 ― Fundamental Concepts of Technical Documentation Introduces basic concepts of technical documentation.
Chapter 2 ― Basic Building Blocks of Information Design Describes how to use different types of information structures.
Chapter 3 ― Grammar and Usage Guidelines Provides advice and examples about how to use specific parts of grammar.
Chapter 4 ― Writing Documentation for an International Audience Provides guidelines to cater for the most common problems encountered by translators of technical documentation.
Chapter 5 ― Ways to Improve Your Documentation Outlines some tips about how you can review and improve your writing.
Chapter 6 ― Indexing Your Documentation Describes basic index requirements and indexing techniques.
Chapter 7 ― Writing for GUIs Describes how to write about GNOME user interfaces.
Chapter 8 ― Usability and Readability Considerations for Technical Documentation Discusses readability issues, and gives some ways to assess readability.
Chapter 9 ― Writing Accessible Documentation Discusses the needs of disabled users of technical documentation.
Chapter 10 ― Use of Screenshots Provides style guidelines for screenshots.
Chapter 11 ― Legal Topics Covers essential legal topics in GNOME documentation.
Appendix A ― Recommended Terminology Provides a comprehensive list of agreed terminology for use in GNOME documentation.
Appendix B ― Units Provides a list of standard units that appear in GNOME documentation, or in the GNOME Desktop.
Appendix C ― Glossary of Terms in This Guide Provides a list of unfamiliar language terms that are used in this guide.
Appendix D ― Examples of Information Design Building Blocks Provides examples of the information design building blocks discussed in Chapter 2 ― Basic Building Blocks of Information Design.
Appendix E ― GDSG Contributors Lists contributors to this guide.

3. Who Should Read This Guide

Different parts of this guide are of different levels of interest to writers, depending on your level of experience, as shown in the following table. The key to the table is as follows:

* You are probably familiar with this material. You only need to refer to this material for reference.
** This information is of interest to you, however other parts of the guide are probably of more immediate interest. You can read these sections when you have time.
*** This information is of immediate interest to you.

Section New Writers Experienced Writers
Chapter 1 ― Fundamental Concepts of Technical Documentation *** *
Chapter 2 ― Basic Building Blocks of Information Design *** *
Chapter 3 ― Grammar and Usage Guidelines *** ***
Chapter 4 ― Writing Documentation for an International Audience *** ***
Chapter 5 ― Ways to Improve Your Documentation ** **
Chapter 6 ― Indexing Your Documentation ** **
Chapter 7 ― Writing for GUIs ** ***
Chapter 8 ― Usability and Readability Considerations for Technical Documentation ** **
Chapter 9 ― Writing Accessible Documentation ** ***
Chapter 10 ― Use of Screenshots ** ***
Chapter 11 ― Legal Topics ** **
Appendix A ― Recommended Terminology *** ***
Appendix B ― Units *** ***
Appendix C ― Glossary of Terms in This Guide ** *
Appendix D ― Examples of Information Design Building Blocks *** *
Appendix E ― GDSG Contributors * *

4. Associated Documentation

The following documentation is also associated with writing GNOME manuals:

5. Related Documentation

See also the following documentation relevant to GNOME documentation:

6. Reference Sources

The following reference sources are relevant to the guidelines in this guide:

1. Fundamental Concepts of Technical Documentation

This chapter provides a brief introduction to writing technical documentation.

1.1. General Style Requirements

Technical writing for computer applications imposes special constraints beyond the basic requirements of good prose. Good technical documentation has the following characteristics:

Comprehensive

Describe all of the functionality of a product. Do not omit functionality that you regard as irrelevant for the user.

Conformant

Describe what you see. Do not describe what you want to see. Present your information in the order that users experience the subject matter.

Clear

Read http://www.bartleby.com/141/ to help make your writing clear.

Consistent

Use agreed vocabulary throughout your documentation. Use the same vocabulary as other writers who are working on related documentation.

Concise

Review your work frequently as you write your document. Ask yourself which words you can take out. See Section 1.2 ― Golden Rules for a specific guideline.

1.2. Golden Rules

This section contains some basic style guidelines. Subsequent chapters of this book expand on these guidelines to give more detailed guidance.

Golden Rule 1
  • Limit each sentence to less than 25 words.
  • Limit each procedure step to 23 words.
Example Under normal operating conditions, the kernel does not always immediately write file data to the disks, storing it in a memory buffer and then periodically writing to the disks to speed up operations.
Rewrite Normally, the kernel stores the data in memory prior to periodically writing the data to the disk.

Golden Rule 2
  • Limit each paragraph to one topic.
  • Limit each sentence to one idea.
  • Limit each procedure step to one action.
Example The Workspace Switcher applet helps you navigate all of the virtual desktops available on your system. The X Window system, working in hand with a piece of software called a window manager, allows you to create more than one virtual desktop, known as workspaces, to organize your work, with different applications running in each workspace. The Workspace Switcher applet is a navigational tool to get around the various workspaces, providing a miniature road map in the GNOME panel showing all your workspaces and allowing you to switch easily between them.
Rewrite You can use the Workspace Switcher to add new workspaces to the GNOME Desktop. You can run different applications in each workspace. The Workspace Switcher applet provides a miniature map that shows all of your workspaces. You can use the Workspace Switcher applet to switch between workspaces.
Tip Plan the order of paragraphs before you start writing. Decide which topic you want to cover in each paragraph.

Golden Rule 3 Use explicit examples to demonstrate how an application works. Provide instructions rather than descriptions.
Example There is a text box that you can use to find out the definition of a word.
Rewrite To request a definition of a word, type the word in the text box, then click on the Lookup button.
Tip Do not apply this guideline too rigidly. Sometimes you must explain how software works to support your how-to examples.

Golden Rule 4 Write in a neutral tone.
Example The applet is a handy little screen grabber.
Rewrite You use the applet to take screenshots.

1.3. Tone

Inappropriate tone can hinder reader access to information. A neutral tone free of opinion or personal flavor reduces the processing load for the reader to understand the information. Another benefit of a neutral tone is that several writers can work in parallel on a large technical documentation project. Furthermore, different writers can join the project at different times. The use of a neutral tone helps to achieve consistency across a documentation set, and thereby facilitates user access to information. The best way to achieve a common, neutral tone is to apply the following principles:

Avoid humor

Humor distracts from the information you are trying to provide. Humor also makes documentation difficult to translate. Stay factual.

Avoid personal opinions

Whether you think a function is useful or woeful is irrelevant. Report the function to the user, with instructions about how to use the function. Stay accurate.

Avoid colloquial language

Colloquial language is difficult to translate and usually culture-specific. Stay neutral.

Avoid topical expressions

An expression that is in common use today might convey something completely different tomorrow. Stay technical.

Avoid aspirational statements

Statements about the future developments of a product do not belong in technical documentation. Write about what you see right now. Stay real.

1.4. Reaching the Right Audience

All of the decisions that you make about the structure and content of a manual follow from an understanding of the audience. You need to think about how the audience accesses the documentation, what sort of information the audience needs, and the experience level of the audience. Usually, you need to create documentation that is suitable for different audiences. The following sections introduce some of the audience-related topics you need to consider.

1.4.1. User Motivation

Do not waste the time of the user who looks for information in your documentation. Users do not read technical documentation for entertainment. Users usually have specific questions. You need to give clear answers to those questions.

1.4.2. New Users

New users to the GNOME Desktop are likely to consult online Help for guidance about unfamiliar applications or functionality. Each Help manual should contain enough introductory information to tell new users how to start using the application. Each Help manual should also contain enough usage instructions to tell users the different actions that they can perform with the application. Keep these instructions task-oriented. You do not need to describe GUI screens, dialogs, and dialog elements in Help, unless there is an unusual feature that affects your instructions.

1.4.3. Experienced Users

Experienced users are more likely to use documentation as a reference. The documentation therefore needs to be complete, well-organized, and in the case of printed manuals, well-indexed.

1.4.4. Do Not Offend Your Audience

To avoid offending your readers, apply the following guidelines to your documentation:

Avoid insider language

Insider language includes both undefined jargon and the tendency of the computer community to shorten words. For example, use the term documentation instead of the term docs. You can identify jargon if terminology fails the following conditions:

Avoid sexist language

Pronoun constructions such as his/her or s/he do not exist. There is no need to identify gender in your instructions.

Avoid culture-specific language

There is little point in giving an example that everyone in your town knows about, but is a complete mystery to everyone else in the world.

Avoid talking down to your reader

There are few experiences more irritating for a user than documentation that says an action is easy or quick, when in fact the user cannot complete the action. Do not qualify or prejudge actions.

Other parts of this guide discuss in more detail tone and language usage that can cause offense.

1.5. Structure

Good organization goes a long way towards creating good documentation. You need to consider the type of manual that you want to create before you start work. Not every manual can follow the same structure. You must break up a complex, multifunction application such as Evolution into many parts, to provide detailed explanations of the separate functional modules. An applet, on the other hand, needs a brief description of the GUI, basic usage instructions, and details on any necessary preferences.

1.5.1. Help Manuals

Wherever possible, use templates to ensure that your Help manual follows a standard approach. You can find templates for Help manuals in the http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/.

1.5.2. Guides

If you need to write a guide about a large application or a set of applications, then the book is substantially longer than a Help manual. You need to develop an outline plan for your guide. The precise composition of your manual depends on the subject, however in general you need the following book components:

Front matter

Defines the function of the book. Includes navigation aids to the remaining sections of the book, such as a table of contents, or links. This section might contain a Preface.

Introduction

Explains the application to new users. You should provide an expanded definition of the function of the application, built around illustrations and examples.

Document body

Consists of several sections or chapters that provide a more detailed explanation of how to use the application. This is where you achieve completeness, telling the user how to complete all the main tasks associated with the application. Chapter headings are usually descriptive of the each topic area. Sub-headings within the chapter are usually task-oriented, so that users can quickly find information about a specific action within the topic area.

Glossary

Defines specific terms in the book. You do not need to define terms that are in the http://www.bartleby.com/61/.

Appendices

Contain additional notes about related topics that are not directly explained in the document body.

Index

Provides keyword links to specific concepts in the book. Follow the guidelines in this guide to create an effective index.

2. Basic Building Blocks of Information Design

This chapter provides a brief introduction to the basic building blocks of information design. You can find information about how to use DocBook tags to create the basic building blocks in the http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/. Appendix D ― Examples of Information Design Building Blocks contains examples of some of the information design building blocks in this chapter.

2.1. Section Headings

A section heading summarizes the information in the associated information block. Use section headings to divide a large body of information into logical chunks.

2.1.1. Guidelines for Writing Section Headings

Use the following guidelines to write section headings:

  • Use a level-one heading to start a broad subject area. Level-one headings are typically generic titles, such as Basic Skills, Getting Started, and so on.

  • Use level-two, level-three, and level-four headings to chunk information into easy-to-identify sections. Use specific titles that summarize the information in the associated sections.

  • Do not use more than four heading levels.

  • Limit the use of level-four headings.

  • Try to have at least two headings within a section.

  • Keep headings short.

  • Use parallel construction in headings of the same level. For example, if you use a gerund to start one heading, use a gerund to start all headings of the same level in the section.

    Correct:

    To Open a File

    To Save a File

    To Edit a File

    Incorrect:

    Opening a File

    To Save a File

    Edit a File

  • Avoid starting a heading with an article.

    Correct: Nautilus File Manager
    Incorrect: The Nautilus File Manager

2.2. Jump Lists

A jump list is a bulleted list of cross-references to the subsections in a chapter or section. Jump lists provide a navigational aid for the reader. For online documents, use hyperlinks for the cross-references.

2.2.1. Guidelines for Writing Jump Lists

Use the following guidelines to write jump lists:

  • Use jump lists consistently in your document. If you use a jump list at the start of one chapter or section, use a jump list at the start of every equivalent section.
  • Use the exact title of the section you are referencing as the text of the jump list item.
  • Keep all of the items in a jump list on the same page if possible.
  • Do not mix heading levels in the jump list. For example, if a chapter contains level-one, level-two, and level-three headings, only list the level-one headings in the jump list at the start of the chapter.

2.3. Tables

Use tables to present large amounts of detailed information that you can structure uniformly. If a paragraph becomes cumbersome and repetitive, consider using a table instead. You can use the following types of table:

Formal table

A formal table is numbered and has a caption. A formal table usually appears in the table of contents of a manual.

Informal table

An informal table is not numbered, and does not have a caption. An informal table does not usually appear in the table of contents of a manual.

2.3.1. Guidelines for Using Tables

Use the following guidelines to create and write the content of tables:

  • Use a complete sentence to introduce the table. Ensure that the introductory sentence puts the table information into context.
  • Do not insert a table between the beginning and end of the same sentence.
  • Write column headings that summarize the information in the column.
  • Use title capitalization rules for column headings and avoid end punctuation except where a question mark or ellipsis is required by the text.
  • Avoid starting a column heading with an article. For example, use "Rule Name" instead of "The Rule Name".
  • Use parallel verb tenses, grammatical construction, voice, and punctuation to write the text content of each table column.
  • Keep column text brief. Remove superfluous words such as articles and repetitive phrases in the column heading.
2.3.1.1. Guidelines for Formal Tables
  • Use a formal table when you want to refer to the table from other sections of the document.
  • Use a formal table when you want the table to appear in the table of contents.
  • Assign an appropriate table caption to a formal table that matches the style of other captions and section headings. Use title capitalization rules for table captions. Position the caption above the graphic.
2.3.1.2. Guidelines for Informal Tables
  • Use an informal table when you do not want to refer to the table from other sections of the document.
  • Use an informal table when you do not want the table to appear in the table of contents.
  • Use an informal table to structure information that occurs in text blocks, such as lists of values.

2.4. Graphics

Use graphics to clarify your subject matter. A graphic can be a screenshot, diagram, graph, chart, or any graphic element. You can use the following types of graphic:

Formal graphic

A formal graphic is numbered and has a caption. A formal graphic usually appears in the table of contents of a manual.

Informal graphic

An informal graphic is not numbered, and does not have a caption. An informal graphic does not appear in the table of contents of a manual.

2.4.1. Guidelines for Using Graphics

Use the following guidelines to include graphics in your material:

2.4.1.1. Guidelines for Formal Graphics
  • Use a formal graphic when you want to refer to the graphic from other sections of the document.
  • Use a formal graphic when you want the graphic to appear in the table of contents.
  • Use a formal graphic for a screenshot at the start of an applet online Help manual. You do not need an introductory sentence for a screenshot of an applet at the start of an applet manual.
  • Assign an appropriate caption to a formal graphic that matches the style of other captions and section headings. Use title capitalization rules for graphic captions. Position the caption above the graphic.
2.4.1.2. Guidelines for Informal Graphics
  • Use an informal graphic when you do not want to refer to the graphic from other sections of the document.
  • Use an informal graphic when you do not want the graphic to appear in the table of contents.
  • Use an informal graphic for graphics that occur in text blocks, such as screenshots of buttons or icons.

2.4.2. Guidelines for Using Screenshots in Online Help

Use the following guidelines for including screenshots in online Help:

  • Include a screenshot of the applet or application at the start of the manual for the applet or application. The screenshot enables users to verify that the manual describes the same applet or application that they are viewing online.
  • Do not use screenshots indiscriminately in online Help.
  • Make sure that each additional screenshot is really necessary. Bear in mind that the user usually has the application open in the GNOME Desktop, so that a screenshot in the Help does not provide any additional information.

Before you decide to use screenshots in online Help, consider the following points:

  • Users must scroll screenshots to get to the next piece of information. Screenshots slow down the user access to information.
  • Help that describes everything in text is more accessible to users with disabilities than Help with text plus pictures. If a screenshot does not provide additional technical information, then the Help is more complex than necessary for disabled users.
  • Usability studies show that users can confuse Help screenshots with the real application.
  • Task-oriented Help requires fewer screenshots than a descriptive approach.
  • There is a requirement to update screenshots with product development. If the screenshot and the product are out-of-step, you risk confusing the user.
  • There is a requirement for accessibility text for every screenshot. You must update this text each time the screenshot is updated. There is a risk of the accessibility text being out-of-step with the screenshot, or with the application. These factors add to the maintenance load for the writer, and can confuse the disabled user.
  • Screenshots add to the localization burden and cost. The localization team has to capture all screenshots in each language. Also, translators have to translate the accessibility text associated with each screenshot into each language.

2.4.3. Guidelines for Using Screenshots in Printed Manuals

Some GNOME Desktop distributions have a requirement to print manuals covering broad topics, such as the http://www.gnome.org/learn/users-guide/2.0/. The same manuals are usually also a source of online Help, therefore you need to consider the requirements for both online Help and for printed manuals. Many of the issues associated with screenshots in online Help also apply to screenshots in printed manuals. However, printed manuals are not always used in conjunction with the application running on the GNOME Desktop. Therefore, you might need to use more screenshots in printed manuals than in online Help.

Use the following guidelines for including screenshots in printed manuals:

  • Do not use screenshots in printed manuals for aesthetic purposes. For example, do not use screenshots for the sole purpose of breaking up long passages.
  • Always ensure that there is a user requirement to see a screenshot in a specific location.
  • Always ensure that the screenshots support the text, rather than repeat what the text says.

2.5. Lists

Lists break information from the standard paragraph format into a concise, organized, easy-to-read format. You can use the following types of lists:

  • Unnumbered lists, also known as bullet lists or itemized lists
  • Numbered lists
  • Lists of terms with a description for each term, known as variable lists

2.5.1. General Guidelines for Writing Lists

Use the following guidelines to write lists:

  • Use unnumbered lists where the entries in the list are of the same importance and do not follow a sequence.
  • Use numbered lists where the entries in the list must follow a sequence.
  • Use variable lists when you need to include short descriptions for a list of topics.
  • Use a complete sentence that ends with a colon to introduce a list.
  • Use a list to put information into context.
  • Do not continue an introductory sentence after the list.
  • Do not connect list items with conjunctions such as "and" or "or".
  • Begin each list item with the same part of speech. For example, in a numbered list begin each list item with a verb.
  • Capitalize the first word of each list item.
  • Use a period at the end of each list item, if one of the items is a complete sentence.
  • Do not use a period at the end of each list item, if the items are phrases, words, or sentence fragments.

2.5.2. Writing Unnumbered Lists

Use unnumbered lists where the sequence of the information is not important. In addition to the general guidelines listed above, use the following guidelines for writing unnumbered lists:

  • Ensure that all list entries are similar in value.

  • Where appropriate use a sublist or nested list to further break out a complex list entry. For example:

    • Main list entry

      • Sublist entry
      • Sublist entry

    • Main list entry

2.5.3. Writing Numbered Lists

Use numbered lists where the sequence of the information is important. For example, use numbered lists for procedures. In addition to the general guidelines listed above, use the following guidelines for writing numbered lists:

  • Only use numbered lists where there are more than two items in the list.

  • For procedures, use the following guidelines:

    • Use a complete sentence with a period for each step.

    • Use a separate step for each action. However, if actions include routine substeps, you can include the substep in the main action. For example, if a step requires the user to press Return at the end of the step, you can include "then press Return" at the end of the step.

    • Where possible begin each step with an active verb in the imperative form. For example:

      1. Choose File ▸ Open.
      2. Select the file you want to open, then click OK.

  • Use clear and concise text in each step. Avoid redundant words.

2.5.4. Writing Variable Lists

You can use a variable list to separate terms from descriptions of the terms, in a list of terms. For example:

The dialog contains the following elements:

Use Proxy check box

Select this option to ...

Username text box

Use this text box to ...

Password text box

Use this text box to ...

2.6. Cross-References

Use cross-references to identify information that is related to a specific topic.

2.6.1. Guidelines for Writing Cross-References

Use the following guidelines for creating and using cross-references:

  • Use cross-references where related information is already described elsewhere in the document and is not essential to the current discussion.

  • Do not include a cross-reference to information that is essential for the reader to understand the current discussion. In this situation, you should restructure the document to include the information in the current discussion, or at least summarize the essential information in the current discussion.

  • Use specific and clear phrases to introduce cross-references.

    Ambiguous: To configure, see Settings.
    Clear: For information about how to configure the applet, see Settings.

  • Use hyperlinks for cross-references in online documentation.

2.7. Tips, Notes, and Cautions

Use tips, notes, and cautions to highlight important information. The following summarizes the differences between tips, notes, and cautions:

Tip

Provides practical but non-essential information that is related to the current discussion. A tip usually describes an alternative method of performing a function. For example:

You can also use the Menu Editor to create a custom menu.

Note

Provides important information that is related to the current discussion but is not imperative. For example:

A window can only be in one window group at a time.

Caution

Provides mandatory information that the user needs to know to protect the user from personal injury or from damaging hardware or software. For example:

Irreversible destruction can occur to data or the operating system. Follow the instructions carefully.

2.8. Endnotes and Footnotes

Use endnotes and footnotes to provide complete cross-references to other sources or to add comments about a discussion. Endnotes are displayed at the end of a chapter or book. Footnotes are displayed at the end of a page or a table. The stylesheet that you use usually determines the format and placement of endnotes and footnotes.

2.8.1. Guidelines for Creating Endnotes and Footnotes

Use the following guidelines for creating endnotes or footnotes:

  • Place the endnote or footnote reference at the end of the sentence, phrase, or quotation.
  • Use consecutive numerals that are displayed in superscript to indicate an endnote or footnote reference.
  • Repeat the numeral at the start of the endnote or footnote text.

3. Grammar and Usage Guidelines

This chapter contains an alphabetical list of grammar and usage guidelines for use in GNOME documentation. Many of these guidelines are only applicable to English-language usage, see the http://www.bartleby.com/61/ and the http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.

Abbreviations
Rules:

A shortened form of a word or phrase that takes the place of the full word or phrase, for example Dr., a.m., p.m., and so on.

Apply the following rules when you use abbreviations:

  • Avoid creating new abbreviations. Unfamiliar abbreviations can confuse rather than clarify a concept.
  • Do not explain or expand familiar abbreviations.
  • Do not include familiar abbreviations in the glossary of your manual.
Adjectives
Rules: Use adjectives with caution. If an adjective is necessary to differentiate between items, then use adjectives. In all cases, test whether the phrase can stand alone without the adjective.
Acronyms
Rules:

A term that represents a multi-word term. Typically, acronyms are formed in the following ways:

  • From the first letters of each word in a compound term, for example Table of Contents (TOC).
  • From recognizable parts of a compound term, such as GNU Object Model Environment (GNOME).

Apply the following rules when you use acronyms:

  • On the first occurrence of an acronym, spell out the full term, with the acronym in parentheses.
  • Do not spell out the full compound for well-known acronyms, unless you think the information is useful for readers.
  • Avoid creating new acronyms. Unfamiliar acronyms can confuse rather than clarify a concept.
  • Write the acronym in uppercase letters, unless there is a compelling case for lowercase.
  • Include the acronym and the full term in the glossary of your manual.
Adverbs
Rules: Use adverbs with caution. If an adverb is necessary to qualify the function of a component, then use an adverb. In all cases, test whether the phrase can stand alone without the adverb. Classic superfluous adverbs are: simply, easily, quickly.
Anthropomorphism
Rules:
  • Do not apply emotions, desires, or opinions to software applications.
  • Do not apply a sense of location or dimension to a software application. You can not be in a text editor.
Apostrophe
Rules:
  • Do not use apostrophes to denote possession.
  • Do not use apostrophes to denote contractions.
  • Do not use apostrophes to denote plurals.
Articles
Rules:

Do not use the definite article the to begin any of the following items:

  • Manual titles
  • Chapter titles
  • Headings
  • Figure captions
  • Table captions
  • Callouts
Brackets
Rules:
  • Do not use brackets [such as these] as a substitute for parentheses (such as these).
  • Use brackets for optional command line entries.
  • Do not use angle brackets to indicate variables in text, instead use the replaceable tag.
Capitalization
Rules:

Capitalize in the following situations:

  • All letters in acronyms, unless the acronym is a well-known exception
  • Initial letter of the first word in a list
  • Initial letter of the first word in a callout
  • Initial letter of a key name, such as the Shift key
  • Initial letter of a sentence. Avoid starting a sentence with a command name or application name that has a lowercase initial letter
  • Initial letter of a complete sentence after a colon

Do not capitalize in the following situations:

  • A compound term that is followed by an abbreviation or an acronym
  • When you want to emphasize something
  • Variable names
  • The initial letter of the first word following a colon, if the word is part of an incomplete sentence
Captions
Rules:
  • Use the same rules as for headings, for all captions accompanying figures and tables.
  • Do not put a period at the end of a caption.
Colon
Rules:

Use a colon in the following situations:

  • To introduce a list
  • Before an explanation
  • After an introduction

Do not use a colon in the following situations:

  • To introduce a figure or a table
  • To introduce headings
  • At the end of an introduction to a procedure

Column headings
Rules:
  • Use the same rules as for headings.
Comma