GNOME.org

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
Rules:

Use commas in the following situations:

  • To separate items in a series
  • To separate the parts of a sentence
  • To separate nonrestrictive phrases
  • Instead of dashes to set off appositives
  • With for example and similar expressions

Do not use commas in the following situations:

  • In a series of adjectives used as one modifier
  • Between two short independent clauses
Commands
Rules: Do not use commands as verbs.
Contractions
Rules: Do not use contractions such as can't, don't, or isn't.
Dash
Rules: Do not use the em dash or the en dash. Use a paragraph break or a colon instead, where you want to create an introductory piece of text. If you have several items that you want to introduce, then you can use a variable list.
Ellipsis
Rules:

Use an ellipsis in the following situations:

  • To show that you have omitted something from a sentence
  • To indicate a pause when you quote displayed text
Fractions
Rules:
  • Use numerals for fractions in tables and in units of measurement, but spell out fractions in prose.
  • Use a space between a numeral and a related fraction, if there is a possible ambiguity. For example: 1 1/2 instead of 11/2.
  • If a fraction is used in a compound modifier, insert a hyphen between the fraction and the unit of measurement.
Gender
Rules: See Section 1.4.4 ― Do Not Offend Your Audience.
Grammar
Rules: Use standard American English grammar rules, see the http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.
Headings
Rules:

Use the following capitalization rules in headings:

  • Initial uppercase letter for the first word and the last word, regardless of part of speech
  • Initial uppercase letter for all nouns, adjectives, and verbs
  • Initial uppercase letter for conjunctions of four letters or longer
  • Initial uppercase letter for prepositions of four letters or longer
  • Initial uppercase letter for prepositions that are part of a phrasal verb
  • All lowercase letters for conjunctions, articles, and prepositions of less than four letters

See Section 2.1 ― Section Headings for more information about headings.

Hyphen
Rules:

Use hyphens in the following situations:

  • With a numeral in a compound modifier
  • To prevent ambiguity
  • With some standard prefixes and suffixes. Use the http://www.bartleby.com/61/ for guidance
  • In spelled-out fractions
  • In variable names of two or more words, such as directory-name. Note: filename is an exception.

Do not use hyphens in the following situations:

  • For industry-accepted terms
  • To construct verbs
  • With an adverb ending in ly
  • With numerals as single modifiers
  • With a word that is listed as unhyphenated in the http://www.bartleby.com/61/, and that uses a common prefix
  • With trademarked terms
Latin terms
Rules: Do not use Latin terms. Use an equivalent English term instead.
Like
Rules: Do not use the term like to denote equivalence or similarity.
Lists
Rules: Introduce a list with a complete sentence that ends with a colon.
Numbers
Rules:

Spell out numbers in the following situations:

  • Numbers from zero through nine unless the number is part of a measurement.
  • Approximations.
  • Extreme values such as million, but precede the value with a numeral
  • Any number that begins a sentence
  • A number that is immediately followed by a numeral, for example: two 10 MB files
Numerals
Rules:

Use numerals in the following situations:

  • The number 10 or greater
  • Negative numbers
  • Most fractions
  • Percentages
  • Decimals
  • Measurements
  • Units of time smaller than one second
  • References to bits and bytes
Parentheses
Rules:

Use parentheses in the following situations:

  • To contain the abbreviation of a term on the first occurrence of the full term
  • In man page references, specifically the section number
Period
Rules:

Use a period in the following situations:

  • To end a sentence
  • In file and directory names
  • In abbreviations that can be mistaken for words, such as a.m. and U.S.
Punctuation
Rules: Use standard American English punctuation rules. In addition to the specific points of punctuation in this section, see also the http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.
Punctuation in numbers
Rules:
  • Do not use a comma in numerals of four digits.
  • Use a comma in numerals of more than four digits.
Quotation marks
Rules:
  • Use quotation marks to indicate material that is taken verbatim from another source.
  • Do not use quotation marks to excuse terms from legitimacy. If the term is not legitimate, then use another term. If you must use that term, declare the term in the glossary and make the term legitimate.
Semicolon
Rules: Do not use semicolons.
Spelling
Rules: Use standard American English spelling rules, see the http://www.bartleby.com/61/ for guidelines.
Titles
Rules: For manual titles use the same rules as for headings.
Units
Rules:
  • Use standard abbreviations for units of measurements, do not invent your own abbreviations.
  • See Appendix B ― Units for a list of units relevant to the GNOME Desktop. For further guidelines, see the IEEE Standard Dictionary of Electrical and Electronics Terms.
  • Use periods for abbreviated units that might be mistaken for a word.
  • Most standard abbreviations of units account for both singular and plural usage.
  • Insert a space between the numeral and the unit of measurement.

4. Writing Documentation for an International Audience

The guidelines in this chapter can help you to create documentation that is suitable for an international audience.

4.1. Goals of the Writer

When you create technical documentation for an international audience, you should aim to achieve the following objectives:

  • Ensure technical accuracy and linguistic clarity, so that translated versions retain the technical accuracy of the original language version.

  • Facilitate the work of the translators. Documentation that is wordy or ambiguous creates more work for the translators. You should aim to reduce to a minimum the time and effort that the translator needs to translate your documentation.

  • Ensure that the documentation is suitable for internationalization, localization, and translation. Consider the following factors:

    • Internationalization involves the creation of documentation for use in many different cultures, or documentation that is easy to translate into many languages.
    • Localization involves the conversion of documentation into another language or culture.
    • Translation refers to the process of translating documents into another language. Translation is just one part of localization. The guidelines in this section can help you to create technical documentation that translators can easily translate into different languages.

4.2. Cultural Differences

You need to think globally when you write for an international audience. Conventions that you take for granted in your own language and culture are often different in other parts of the world. Keep in mind the following guidelines when you write for an international audience:

  • Do not use examples that are culturally bound, such as names of places that are unrecognizable to people in other countries.
  • Do not use political or religious references. Make sure that when you give examples, the machine names, login names, and so on are not culturally offensive. Do not use examples from political or religious spheres.
  • Be aware that calendar conventions vary from country to country.
  • Do not use humor. A great joke in one culture can provoke complete bewilderment in another culture.
  • Do not use colloquial language. Everyday sayings are very difficult to translate and are usually meaningless if the translator translates the saying word-for-word. If you use colloquial phrases then the translator has to interpret what you want to say, which can cause ambiguity or inaccuracy.

4.3. How to Write for Translation

This section provides you with specific rules about how to write for translation, with practical examples. The topics in this section are the most common causes of translation errors. You can use the following basic grammar guidelines to avoid most situations that cause difficulty for translators and readers. The examples for each topic might relate to releases of the GNOME Desktop that predate the release you are working with, nevertheless the linguistic points remain valid.

Topic 1 Gerund
Rule Do not use a gerund where a translator can mistake the gerund form for an adjective. The most common place for this problem to occur is when a gerund immediately precedes a noun.
Example Clicking Programs opens the Programs menu.
Rewrite Click on Programs to open the Programs menu.
Exceptions
  1. You can use the gerund in section headers, for example: Using the Menu Editor.
  2. You can use the gerund in the present continuous tense, for example: The application is running.
  3. You can use the gerund for the term Settings, for example, when you describe controls in a dialog.
  4. You can use the gerund for the adjective following, when you introduce a list or a procedure.
  5. You can use gerunds preceded by an article when the gerund is a noun, for example, the setting.

Topic 2 Passive voice
Rule Use the active voice wherever you can. If you do use the passive voice, analyze the text to see if you can say the same thing in the active voice.
Example The Menu Editor is started from the Main Menu.
Rewrite You start the Menu Editor from the Main Menu.
Exceptions Sometimes you cannot avoid the passive voice. If the sentence does not make sense in the active voice, then use the passive voice, but limit the occurrences.

Topic 3 Indefinite pronouns
Rule Restrict the use of indefinite pronouns such as it, this, and those, especially at the beginning of sentences.
Example The Menu Editor is a configuration tool for the Main Menu. It is very useful in setting your system to your system requirements.
Rewrite The Menu Editor is a configuration tool for the Main Menu. The Menu Editor provides a useful way to set your system requirements.
Exceptions Very restricted usage only.

Topic 4 Future tense
Rule Use the present tense in your writing wherever you can. Do not use the future tense, or future passive tenses.
Example 1 In the menu tree you will notice that there are two main menu lists.
Rewrite 1 The menu tree contains two main menu lists.
Example 2 In the menu tree you will have noticed that there are two main menu lists.
Rewrite 2 The menu tree contains two main menu lists.
Exceptions Restrict the use of the future tense to only those circumstances that will happen at some future point in time, such as next year.

Topic 5 There is, there are
Rule The terms there is and there are are ambiguous. Do not use these terms.
Example In the menu tree there are two main menu lists.
Rewrite The menu tree contains two main menu lists.
Exceptions Limit your use of these terms. Test your text to see if you can phrase the sentence with a more definite verb.

Topic 6 Sentence length
Rule See Section 1.2 ― Golden Rules.
Example If you would like to place a menu item onto the panel, you can drag and drop from the menu to the panel and it will place a launcher there with all the appropriate properties set for you.
Rewrite You can drag a menu item from the menu to the panel. The drag action places a launcher on the panel with all the appropriate properties set.
Exceptions Legal statements.

Topic 7 How to introduce lists and procedures
Rule See Section 2.5 ― Lists.
Example In the Properties dialog select:
Rewrite In the Properties dialog select the following parameters:
Exceptions

Single nouns in front of a colon are acceptable, as opposed to a sentence fragment. For example, if the preceding paragraph discusses parameters, you can introduce the list of parameters in the following way: Parameters:

Also note the use of the gerund following in this context.

Topic 8 Parentheses
Rule Use parentheses to introduce abbreviations that you will use later, such as GNOME Documentation Project (GDP). Do not use parentheses to provide explanations.
Example The theme files should be in a tar.gz or .tgz format (otherwise known as a tarball).
Rewrite The theme files are usually in a tar.gz or .tgz archive file, known as a tarball.
Exception None.

Topic 9 Rank of structures within a sentence
Rule Repeat noun modifiers to make structures equal in rank in a sentence.
Example You can start applications from panel menus or objects.
Rewrite You can start applications from panel menus or panel objects.
Exception None.

Topic 10 Semicolons
Rule See the entry for Semicolons in Chapter 3 ― Grammar and Usage Guidelines.
Example The first option in the dialog is selected; all the other options are unselected.
Rewrite The first option in the dialog is selected. All the other options are unselected.
Exception None.

Topic 11 Personal pronouns
Rule Do not use personal pronouns other than you. See also the entry for Gender in Chapter 3 ― Grammar and Usage Guidelines.
Example We recommend this method of moving a symbolic link.
Rewrite Use this method to move a symbolic link.
Exception None.

Topic 12 May
Rule Replace may with can or might.
Example These settings may be accessed from the GMC Preferences dialog. You may launch this dialog by selecting the Preferences item from the Settings menu.
Rewrite You can access these settings from the GMC Preferences dialog. To launch this dialog select the Preferences item from the Settings menu.
Exception Use may only when you grant permission to do something.

Topic 13 Possessive apostrophe 's, Saxon Genitive. See Appendix C ― Glossary of Terms in This Guide.
Rule Replace the genitive construction with an of structure. See also the entry for Apostrophe in Chapter 3 ― Grammar and Usage Guidelines.
Example You can configure a drawer's properties by right-clicking on the drawer's icon and selecting Properties.
Rewrite To configure the properties of a drawer, right-click on the drawer and select Properties.
Exception Use the genitive construction for named individuals, for example: Bob's book.

Topic 14 Contractions
Rule Replace contractions with the relevant complete words. Especially avoid the 's contraction for is and has. Translators can confuse these contractions with each other, or with the Saxon genitive or even with plurals. See also the entries for Apostrophe and Contractions in Chapter 3 ― Grammar and Usage Guidelines.
Example If you're new to GNOME...
Rewrite If you are new to GNOME...
Exception Only use a contraction if you cannot find a reasonable alternative.

Topic 15 Exotic tenses
Rule Write in the present tense. Avoid conditional phrases and past tenses.
Example If you are missing any drives that might have been added to your machine, you may right mouse click on the desktop and choose...
Rewrite If any drives are missing from your machine, right-click on the desktop and choose...
Exception None.

Topic 16 Gender-specific references
Rule See Section 1.4.4 ― Do Not Offend Your Audience.
Example Tell the user to reset his password.
Rewrite Tell the users to reset their passwords.
Exception None.

Topic 17 Articles
Rule Do not omit articles in prose.
Example Open Main Menu and select item.
Rewrite Open the Main Menu and select an item.
Exception None.

Topic 18 When, if
Rule
  • Use when for an inevitable event.
  • Use if for a conditional event.
Example 1

When the prompt is displayed.

This sentence implies that the prompt is definitely displayed. The only question is when the prompt is displayed.

Example 2

If the prompt is displayed.

The sentence says that the prompt might, or might not, be displayed.

Exception None.

Topic 19 Colloquial language
Rule See Section 1.3 ― Tone.
Example The Modem Lights Applet is a handy applet that will start your dialup connection.
Rewrite The Modem Lights applet starts your dialup connection.
Exception None.

Topic 20 Conjoined sentences
Rule Do not join sentences with conjunctions such as and or so. Instead, create two sentences.
Example At the time of publication of this manual there were not any applications that offer full session management for your data, so until there are some and you are aware of their capabilities you should not rely on session management to save your application.
Rewrite At the time of publication of this manual there were not any applications that offer full session management for your data. Do not rely on session management to save your session, until you have a reliable session-management application.
Exception Use conjoined sentence structures only for short sentences.

4.4. Terminology Considerations for Translation

Translators or readers can sometimes misinterpret your text, for example if you use synonyms for the same concept. Use the following guidelines to avoid common areas of misinterpretation:

  • Use terms that are defined in the http://www.bartleby.com/61/.
  • Use terms that are defined in Appendix A ― Recommended Terminology.
  • Define new terms the first time that they appear in text. If your manual has a glossary, then you should include the new terms in the glossary. You should also include the new term in Appendix A ― Recommended Terminology. Contact Eugene O'Connor with your suggestions for new terms.
  • Do not use terms that are jargon or slang.
  • Do not use terms that have several different meanings.
  • Use your defined terms consistently throughout your documentation. Do not use synonyms.
  • Do not use the same word for several different meanings.
  • Ensure that your spelling is correct. Use the http://www.bartleby.com/61/ as your standard for spelling. Use your spellchecker. Work with a copy editor whenever possible.
  • Use consistent uppercase and lowercase rules throughout your documentation.
  • Avoid general adjectives that a translator can interpret in several ways. For example, the user-friendly GNOME Desktop. A translator has to decide whether GNOME is user-friendly, or the Desktop.

5. Ways to Improve Your Documentation

This chapter provides you with tips that can help you to improve the readability and effectiveness of the documentation that you write. This chapter does not describe how to troubleshoot the XML code in your document.

5.1. Reviews

Good reviews are the secret of good documentation. This section tells you about the different types of review that you can use during the development of documentation. In the ideal project, every item of documentation goes through each of the following reviews in the given order, and each review type is completed before the next review type is started.

5.1.1. Technical Review

The developer is your main source of information for the products that you write about. Use the developer as a source of expert knowledge to do the following reviews:

  • Initial review of the first draft for technical accuracy and to ensure that all functionality is documented.
  • Final technical verification review after you have implemented all comments from other reviewers.

5.1.2. Peer Review

Make an agreement with a colleague writer to review your work. The ideal conditions for a peer review are as follows:

  • The reviewer is not familiar with the product before the review.
  • The reviewer reviews your documentation against the product functionality to ensure that all descriptions and instructions are correct.

5.1.3. Editorial Review

An editorial review is essential. You should make a formal arrangement for an editor to review your work. Allow plenty of time for an editorial review, in advance of the date you plan to submit the documentation.

The editor checks the documentation against the agreed standards that you use to write the documentation. The editor ensures that you have followed general structural rules, for topics such as capitalization, spelling, punctuation, and grammar. The editor also ensures that the documentation adheres to specific rules such as terminology defined in Appendix A ― Recommended Terminology.

5.1.4. User Review

Ask someone who is not familiar with the product to try out the product. Set a series of tasks for the user to complete. Instruct the user to refer to the documentation during the execution of the tasks. This type of review answers the following questions about the documentation:

  • How easily can users find relevant information?
  • How easily can users transfer information to the product?
  • What user information is missing?
If you need help setting up a user review, ask the GNOME usability team, or another author who has done such a review.

Practicalities make a user review a rare treat, rather than an expected part of the documentation process.

5.1.5. Publication Review

Ask a colleague to have a quick glance through the document to ensure publication readiness.

5.2. Checks You Can Do Yourself

You can do a variety of checks on your writing during the development of your documentation, in the following areas.

5.2.1. Top-Level Checks

You can perform the following top-level checks regularly during documentation development:

  • Wordcount

    As soon as a sentence or a procedure step starts to look suspiciously long, do a wordcount. See Section 1.2 ― Golden Rules, Golden Rule 1.

  • Spellcheck

    Run regular spellchecks. Make sure that agreed terms from Appendix A ― Recommended Terminology are in your spellchecker dictionary.

  • Pronouns search

    Search for the following pronouns:

    • It
    • They
    • Them

If you find any of the above pronouns, rewrite the sentences to eliminate the pronoun.

5.2.2. Top Ten Topics to Watch Out For

The following table lists the top ten topics that you need to watch out for when you review your work, or when you perform a peer review for a colleague. Review the documentation against the typical problem areas listed in the table. The problem areas in the table are not exhaustive, you may encounter more pitfalls during your review. The table provides you with cues so that you can review your work with these topics and problem areas in mind. You can find advice about how to deal with these topics in other sections of this style guide.

Topic Typical Problem Areas
Accuracy
  • Functions differ from the description.
  • Functions are not described
  • Functions are referred to using different terminology from the user interface.
  • Functions are described that do not exist.
  • The description provides irrelevant and possibly confusing information.
Clarity
  • Ambiguous statements
  • Inconsistency
  • Unexplained events
  • Undefined terms
  • Vague, defensive language
Editorial
  • Repeated words
  • Misspelled words
  • Typographical errors
  • Missing words
  • Verbs in the wrong tense
Grammar and Syntax
  • Tenses other than the present tense
  • Long sentences joined by conjunctions, such as and.
  • Long sentences with confusing subordinate clauses
  • Incomplete sentences that leave out the articles
  • Over-elaborate sentence structure and syntax.
Graphics
  • Wrong graphic referred to in text.
  • Graphic has different features from the description.
  • Unnecessary use of formal figures.
  • Incorrect use of informal figures.
  • Graphics do not adhere to graphics style rules.
Information Design
  • Series of points are described in prose rather than an itemized list.
  • Sequences of actions are described in prose rather than a numbered list.
  • Topics are described in sequential paragraphs rather than in tables.
  • Information is ordered incorrectly within a document.
  • Unclear or insufficient examples to support the descriptions.
Legal
  • Unsubstantiated claims
  • Incorrect description of functions
  • Insufficient notice of potential damage or hazard
  • Statements about future features
  • Statements about competing products
Punctuation
  • Use of slash, and and/or
  • Inconsistent use of hyphens and dashes
  • Inappropriate use of parentheses and brackets
  • Incorrect use of apostrophes
  • Incorrect use of quotation marks
Style and Usage
Tone
  • Jargon
  • Colloquial language
  • Humor
  • Culture-specific references
  • Gender-specific language
  • Condescension

6. Indexing Your Documentation

This chapter provides you with tips that can help you to effectively index your documentation.

6.1. Index Essentials

An index helps users to find the information they need in the documentation that you write. A good index records every pertinent statement in the body of the text. The subject matter and purpose of each section in your book determine which statements are pertinent and which are peripheral. Deciding which statements are pertinent is a judgment call, and the task that causes most difficulty for writers. These guidelines help you to recognize and label statements for an index.

6.1.1. Topics to Index

Consider the following points when you look for pertinent statements to index:

  • A pertinent statement can be a single phrase, a sentence, a paragraph, or even several pages.
  • Begin the search for pertinent statements in the first paragraph of the main body of your manual.
  • Conclude your search for pertinent statements on the last page of the last appendix.
  • Do not index the front matter.
  • Indexing the glossary can provide a useful source of information for the user but is not essential, especially for manuals that appear in print as well as online.

Statements that refer to the following topics are often pertinent for an index:

  • Definitions
  • Restrictions
  • Acronyms
  • Commands
  • Command qualifiers
  • Routines
  • Data structures
  • Key functions
  • Procedures and tasks
  • Tips, notes, and cautions
  • Examples, tables, and figures

6.1.2. How to Compose Index Entries

When you identify a pertinent statement, you need to flag the statement in a way that alerts the user to the information. This flag is the index entry. When you compose an index entry, you must first determine the topics that relate to the statement. These topics become the primary entries. Next, you must determine the nature of the information in the statement relating to each topic. These descriptions become the secondary entries.

6.1.2.1. Primary Entries

Make your primary entries precise, logical, and consistent with the terminology in the rest of the documentation set. Some tips:

  • Make your primary entries nouns or a noun phrase that a user might look for. For example:

    Applications Noun.
    Starting applications Noun phrase.

  • Do not use verbs or adjectives standing alone, because users are unlikely to search for these words.

  • Make sure that the term used for the primary entry appears on the page to which the index points.

6.1.2.2. Subentries

A subentry is a verb, phrase, or adjective that describes the nature of the information about a topic. You can also use nouns and noun phrases for subentries. For example:

Applications

menu

starting from menu

starting from command line

See the http://developer.gnome.org/projects/gdp/handbook.html, Indexing for more examples of index subentries.

6.1.3. Index Navigation

You can use the following types of cross-references to help users to navigate the index:

See

Use this cross-reference to point from a synonym to the term under which the user can find the index entries.

See also

Use this cross-reference to point the user to topics that are related to the original entry.

6.2. How to Evaluate Your Index

When you create an index for a manual, you need to check the index for the following attributes:

  • Balance and structure
  • Clarity and consistency

6.2.1. Balance and Structure

Check the index for the following common problems:

Overloaded primary entries

If you find that a small number of primary entries in your index have a large number of subentries, try to find other labels for some of the subentries. Try to keep the number of subentries to a useful level.

Inadequate subentry labels

If your subentry labels are too cryptic, for example just page numbers, then the reader does not have enough pointers to decide where to go in the book for the required information.

Unbalanced entries across the book

If one or two chapters in the book are heavily represented in the index, then you need to look at the indexing frequency in the other chapters. Also, you might want to look at the overall information design structure of your book, to see if you really need those other chapters.

6.2.2. Clarity and Consistency

To check the index for clarity and consistency, perform the following actions:

Ensure that all primary entries are nouns

Look through your index for primary entries that are verbs and adjectives. Replace the verbs and adjectives with nouns or noun phrases.

Clarify the relationship between primary entries and subentries

Make sure that the subentries bear a meaningful relationship to the primary entries.

Correlate primary entries and subentries

Make sure that related subentries are all gathered together under the same primary entries.

6.3. When to Index GNOME Documentation

When you want to index a manual, you need to consider the type of documentation:

Online Help

As Scrollkeeper is still a product in development, the use of indexing is not yet clear. Until the situation clarifies, you only need to put a single index entry into each online Help manual to create a primary entry for the application name. The template for the online Help manuals provides an example of where to create the index entry in the online Help manual. When the role and function of Scrollkeeper becomes clearer, writers can apply more of the indexing principles outlined in this chapter.

You can find out more about the templates in the http://developer.gnome.org/projects/gdp/handbook.html.

Printed manuals

Apply the indexing principles outlined in this chapter to printed manuals.

7. Writing for GUIs

This chapter provides guidelines about how to document graphical user interfaces (GUIs) in the GNOME Desktop.

7.1. GUI Basics

A graphical user interface (GUI) provides the user with an intuitive way of interacting with a computer and computer applications. The main purpose of a GUI is to make the activities involved in doing a task simple and quick. GUIs include elements that users use to work with applications, and elements that display information to the users.

GNOME documentation must cater for the following GNOME GUIs:

  • GNOME Desktop GUI
  • Application GUIs
  • Applet GUIs

The GNOME Desktop GUI includes the following elements:

  • Buttons
  • Desktop
  • Dialogs
  • Menus
  • Panels
  • Windows

7.2. Writing About GNOME Desktop GUIs

When you write about GNOME Desktop GUIs, observe the following guidelines:

  • Provide only the essential details or information that the user needs to know to accomplish a task.

  • Refer to windows and dialogs by the title of the window or dialog. Refer to menus by the title of the menu, or by the name specified for the menu in Section 7.5 ― Menu Terminology.

    Avoid repeated use of the same name when the meaning is clear. For example: you instruct the reader to choose File ▸ Print, with the expected result that the Print window is displayed. In this case, you do not need to repeat "in the Print window", if there is no ambiguity about which window you want the user to work in.

  • Write the names of dialog elements and menu commands as they appear in the GUI. If the name includes a colon or an ellipsis, do not include that punctuation when you refer to the item in your documentation.

  • Mention certain technical GUI distinctions only when necessary. For example, mention that a menu is a popup menu only if that information is relevant to the task that the documentation describes.

When writing about the GUI, reserve certain verbs for specific activities. For a list of the verbs to use when writing about the GUI, see Section A.4 ― User Actions.

When you write about the mouse, note the following:

  • Refer to the buttons on the mouse as mouse buttons to avoid confusion with buttons in dialogs.
  • Refer to the indicator that shows where the mouse action occurs as the pointer or mouse pointer. Write about the pointer to keep the user focused on the screen. For example, describe moving the pointer, not moving the mouse.
  • The plural for mouse is mouse devices.

7.3. GNOME Desktop Terminology

The following terms are of prime interest when you write about the GNOME Desktop:

Use the terminology shown in Figure 7-1 when you write about GNOME Desktop components.

Figure 7-1 GNOME Desktop Terminology

For more detailed information on the terms in Figure 7-1, see Appendix A ― Recommended Terminology.

7.4. Panel Terminology

A panel is an area in the GNOME Desktop from which you can run applications and applets, and perform other tasks. Use the terminology shown in Figure 7-2 when you write about panels.

Figure 7-2 Panel Terminology

For more detailed information on the terms in Figure 7-2, see Appendix A ― Recommended Terminology.

7.5. Menu Terminology

A menu or a submenu is a list of commands. Table 7-1 lists and illustrates some of the menus in GNOME GUIs. Use the terms in Table 7-1 when you need to refer to a particular menu.

Note that you do not need to specify the name of a menu when you refer to commands on the menu. For example, you can write "To add an object to a panel, right-click on the panel, then choose Add to Panel".

Table 7-1 Menu Terminology
Menu Example
Applet popup menu
Desktop menu
Main Menu
Menu item popup menu
Panel popup menu
Panel object popup menu
Window Menu

For more detailed information on the terms in Table 7-1, see Appendix A ― Recommended Terminology.

7.6. Window Terminology

A window is a rectangular frame that displays a particular application. Typically, applications have one main window from which users can open secondary windows, called dialogs. Use the terminology shown in Figure 7-3 when you write about windows.

Figure 7-3 Window Terminology

A window frame is a border around a window. You can use the window frame to perform various actions on the window. In particular, the titlebar contains various active control elements. Use the terminology shown in Figure 7-4 when you write about window frames and the elements in window frames.

Figure 7-4 Window Frame Terminology

A pane is a subdivision of a window. For example, a Nautilus window can contain two panes: a side pane and a view pane. Figure 7-5 shows panes in an Evolution Inbox window.

Figure 7-5 Window Pane Terminology

For more detailed information on window terms, see Appendix A ― Recommended Terminology.

7.7. Dialog Terminology

A dialog is a popup window in which the user enters information or commands. Dialogs can contain control elements that the user can work with to select an option, specify a value, and so on. Table 7-2 lists and illustrates the dialog elements in the GNOME Desktop GUI. Use the terms in Table 7-2 when you write about dialog elements.

Table 7-2 Dialog Terminology
Element Example
Check box
Color wheel
Column heading
Drop-down combination box
Drop-down list
Drop-down section
Field
Group box
List box
Radio button
Scrollbar
Slider
Spin box
Tab
Tabbed section
Table
Text box

For more detailed information on dialog terms, see Section A.2 ― GNOME Desktop Terms.

7.8. Button Terminology

Table 7-3 lists and illustrates some of the button types that you can use in GNOME Desktop GUIs. Use the terms in Table 7-3 when you write about buttons.

Table 7-3 Button Terminology
Button Example
Arrow buttons
Color selector button
Command button
Font selector button
Icon selector buttons
Main Menu button
Toggle buttons
Toolbar buttons
Window frame buttons
Window list buttons

For more detailed information on GUI buttons, see Section A.3 ― Buttons in the GNOME Desktop.

8. Usability and Readability Considerations for Technical Documentation

This chapter discusses the usability topics that you need to consider to create effective technical documentation. This chapter also briefly discusses readability tests for documentation.

8.1. Usability Objectives

The usability objectives for effective technical documentation are as follows:

  • Maximize speed of access to key information.
  • Present accurate and complete information.
  • Present specific information about specific topics.
  • Make the most effective use of the delivery method, for example, online Help.
  • Make the documentation the resource of choice for regular access, rather than, for example, asking colleagues how to perform actions.

8.2. Things You Are Not Trying to Do

You also need to make sure that you do not inadvertently achieve the wrong objectives. For example:

  • Do not try to resolve inadequate interface design in the documentation.
  • Do not try to fix functionality bugs in the documentation.
  • Do not distract from the task the user wants to perform.

8.3. Strategies for Usability

Strategies that maximize usability must do the following:

  • Reduce the burden on the short-term memory of the reader. Research shows that the average person can retain 7 ± 2 chunks of information in short-term memory. This does not necessarily mean that you must limit sentence lengths to seven words. You can group words together in familiar patterns to form single chunks of information. However, research also shows that a sentence length of more than 25 words overwhelms short-term memory.
  • Build understanding and recognition of terms and structures into long-term memory. Research shows that consistent usage is the best way to achieve this goal. The more information that the reader stores in long-term memory, the lower the burden on the short-term memory.
  • Provide clear navigation techniques.
You can employ the following strategies to maximize the usability and readability of your documentation.

8.3.1. Eliminate Superfluous Information

Superfluous information gives rise to the following usability issues:

  • Increases the amount of text that a reader has to understand before reaching the required information.
  • Increases the amount of time and effort that a reader has to invest to access information.
  • Takes up space in the short-term memory of the reader.
  • Drains mental resources. The reader has a limited amount of mental resources. The more mental resources that reading the documentation takes up, the less mental resources are available for the reader to perform the required actions.
  • Introduces the potential for confusion.
Examples of superfluous information are as follows:
  • Unnecessary adjectives and adverbs
  • Additional sentences that explain a concept in a slightly different way
  • Information about other topics that is not relevant
  • Personal opinions
  • Speculation about future product functions
  • Rhetorical questions
  • Over-exposed legal information
  • Over-exposed author information

8.3.2. Create Consistent Structures

Create your documentation with repeated structures, using the same hierarchy of sections and the same type of information in the sections. By repeating the hierarchy of information structure throughout a documentation set, you train the user to look for certain types of information in certain places.

The structure of the documentation is like a street map. Obviously, a street map that is consistent across the whole of a city area is a better navigation tool than a street map that is inconsistent. The intrinsic, repeated structure of your document needs to feature all of the following characteristics:

  • Orderly
  • Logical
  • Consistent

8.3.3. Use Modular Information Blocks

Create modules that are short enough to reduce scrolling or page-turning to a minimum. Aim to eliminate scrolling or page turning completely for each individual module of information.

8.3.4. Use Consistent Language

At school, teachers tell you to vary your writing so as to hold the interest of the reader. Technical documentation requires the opposite approach. Use the same vocabulary for the same purpose throughout your documentation. Furthermore, when a team of writers work together, they must write with a single voice.

You expect the terminology in a street map to be the same for the whole map. You do not expect particular areas of the map to have personalized terminology. Similarly, use of consistent language by a team of writers across the whole documentation set ensures that the reader is not confused by conflicting terminology.

Repeated use of consistent language builds long-term memory, and therefore reduces the demand on short-term memory. The reader can access the real information content of your text.

Other language points that you need to consider:

  • Research shows that words with Latin and Greek roots are harder to understand than equivalent plain English words.
  • Do not use non-English words, for example, Latin terms. Some readers might not understand the non-English word. Even readers that do understand the non-English word might need to pause and think about such a word.
  • Short words are easier to process in short-term memory than long words.
  • The active voice is easier to understand than the passive voice.
A major benefit from all writers in a documentation team using consistent language, is that localization is made easier. Localized versions of documentation add another dimension to documentation usability.

8.3.5. Use Consistent Typographic Conventions

Where documentation structure is like a street map, typographic conventions are like street signs and road markings. Typographic conventions such as capitalization rules, punctuation, and emphasis tell readers what to expect. Consistent typographic conventions provide the inner structure of a documentation set. Inconsistent typographic conventions confuse and distract the reader.

Imagine the confusion if one area of a city uses different street signs and road markings than other areas. Or worse, imagine the chaos if one area of a city uses the same road markings as everywhere else, but to mean different things. No-one is in danger from inconsistent typographical conventions in a manual, however readers might not revisit the documentation if the conventions are confusing.

8.4. Readability Tests

The main function of readability tests is to give you a quick assessment about the density of your writing. Readability tests cannot tell you how easily a reader can understand the information in the text.

You can perform readability tests manually by counting and doing a mathematical calculation, or by using word-processing software. There are several popular readability indexes, for example:

  • Gunning Fog Index
  • Flesch Reading Ease Scale
  • Flesch-Kincaid Grade Index

8.4.1. Gunning Fog Index

To calculate the Gunning Fog Index of a passage, do the following:

  1. Count the number of words in the paragraph: W
  2. Count the number of sentences in the paragraph: S
  3. Count the number of words of three syllables or more: T
  4. Apply the following formula: [W/S + T/(Wx100)] x 0.4
The Gunning Fog Index gives the number of years of education that your reader needs to understand the paragraph. Typically, in technical documentation, aim for a Gunning Fog Index between 10 and 15. The Gunning Fog Index formula implies that short sentences written in plain English achieve a better score than long sentences written in complicated language.

8.4.2. Flesch Reading Ease Scale

Calculate the readability of a passage on the Flesch Reading Ease Scale in the following way:

  1. Calculate the average sentence length: L
  2. Calculate the average number of syllables per word: N
  3. Calculate the score between 0 and 00%.

The higher the score, the easier the text is to understand. Aim to maximize the score. The Flesch Reading Ease Scale measures readability as follows:

100 Very easy to read. Average sentence length is 12 words or less. No words of more than two syllables.
65 Plain English. Average sentence length is 15 to 20 words. Average word has two syllables.
0 Extremely difficult to read. Average sentence length is 37 words. Average word has more than two syllables.

Click on the following link to find out more about the Flesch Readability Test. In this link, Rudolf Flesch, the developer of the test, provides some background information.

8.4.3. Flesch-Kincaid Index

This index computes readability based on the average number of syllables per word and the average number of words per sentence. The score indicates the number of years of combined primary and secondary education that a reader needs to understand a text. For example, a score of 8.0 means that you can understand the text after eight years of combined primary and secondary education. Standard writing achieves around 7.0 to 8.0 on the Flesch-Kincaid Index.

Click on the following link to find out more about the Flesch-Kincaid Index and other readability tests. Although this web page deals with textbooks, you can also apply the concepts to technical documentation.

9. Writing Accessible Documentation

This chapter provides some basic guidelines for writing GNOME documentation for users with disabilities.

9.1. Assistive Technologies

Wherever possible, consider the requirements of the following groups of users when you write documentation:

  • Users with cognitive impairments
  • Blind users and users with other vision impairments
  • Deaf users and users with other hearing impairment
  • Paralyzed users and users with impaired motor skills

Assistive technologies exist to help computer users with various disabilities. An example of assistive technology is the screenreader, which blind people use to view a GUI and read online text. A screenreader normally translates text into synthesized speech or a refreshable Braille display.

9.2. Information Design Considerations

Consider the following factors relevant to disabled users when you write documentation:

Text blocks

Long text blocks can be difficult to read for people who use screenreaders. Also, readers whose first language is not standard English, including some deaf people, can find long text blocks difficult to understand. Keep your text blocks short. See Section 9.3 ― Accessible Writing Techniques for more information.

Graphics

Do not overuse graphics, especially when you write online Help. A graphic that merely repeats a text message can frustrate someone who is using assistive technology to read the Help. Provide descriptions that do not require graphics. To test whether you need a graphic, remove the graphic, then check whether you can still work out what to do. If you need to use a graphic, make sure that you include a text equivalent of the graphic. See Section 9.4 ― Text Equivalents for Graphics for more information.

Tables

Tables can cause problems for screenreaders that read the content of all the cells as a single, continuous line of text. Use tables for genuinely tabular information only. Do not use tables merely as a layout technique. Ensure that tabular information makes sense if you read the cells in sequence from left to right, starting from the top left cell in the table.

9.3. Accessible Writing Techniques

The following guidelines can help you to develop an accessible writing style:

  • Write concise descriptions to help people with cognitive, vision, and hearing impairments. As recommended elsewhere in this guide, keep sentences to one idea. Do not ramble.
  • Keep the number of steps in procedures to a minimum. More than seven procedural steps can create problems for all users, but pose additional difficulties for people with cognitive impairments.
  • Do not use directional instructions, if at all possible, such as above, below, left, right. Users who are using a screenreader might have difficulty finding the directions on screen. Some users with cognitive impairments might have difficultly understanding the spatial concepts.
  • Emphasize important information near the beginning of the text, so that blind users and users with cognitive impairments can assess whether they need to read further.

9.4. Text Equivalents for Graphics

Graphics such as illustrations, icons, photos, screenshots, and thumbnails all require text equivalents for use with assistive technologies. Each text equivalent should briefly identify the graphic and, if appropriate, describe any functionality that the image represents. The text equivalent must be brief, descriptive, and accurate. You need to include as much information as possible into the fewest number of characters without sacrificing intelligibility

9.4.1. Creating Text Equivalents

A text equivalent should describe the visual appearance of the graphic. The text equivalent can also include instructions on how to take an action, such as how to select options in a dialog. Ideally, a text equivalent provides the user with the same information as the original graphic. To find out how to implement text equivalents in your documentation, see the http://developer.gnome.org/projects/gdp/handbook.html.

9.4.2. Writing Good Text Equivalents

To comply with Part 1194.22 in Section 508 of the Rehabilitation Act: Electronic and Information Technology Accessibility Standards, documentation must include a text equivalent for each graphic in documentation.

Follow these guidelines when you write text equivalents:

  • At a minimum, include the graphic content and the label of the item in the graphic. For example, "Run Application dialog."
  • If the contents of the graphic are not complex, describe the contents of the graphic. For example, "Run Application dialog. Contains command drop-down combination box, Browse button, Run in terminal check box. Contains Run, Cancel, Help buttons."
  • If the contents of the graphic are complex, summarize the contents of the graphic. For example, "Miscellaneous tabbed section. Contains controls to set miscellaneous Sawfish options. Contains Done, Cancel buttons."
  • If the order of use of elements in a graphic is not clear, describe the elements in top-to-bottom, left-to-right order.
  • If the graphic is annotated, list the callouts in order of the elements that are illustrated. This is not necessarily the same as the order in which the callouts appear. For example, "Crux window titlebar. Callouts: Window Menu button, Titlebar, Minimize, Maximize, Close Window buttons."

9.5. More Information About Accessibility

For more information about accessibility topics, read the following documents:

10. Use of Screenshots

This chapter provides guidelines for creating and using screenshots in GNOME documentation.

10.1. Default Settings

As far as possible, use the default settings for the GNOME Desktop when you take a screenshot. Include the window frame when you take a screenshot of a window.

10.2.  Required Formats

For documentation that is for online display, you must use PNG format for screenshots.

10.3.  Image Width

The maximum image width is 510 pixels. At this width, images fit on a printed page. You might need to scale down the image before you add any callouts, to ensure that the total width of the image is less than 510 pixels. You can use GIMP to scale images before you add callouts. To scale an image in GIMP, right-click on the image, then choose Image ▸ Scale image.

10.4.  Special Graphic Effects

Do not use drop-shadow or any other special graphic effects on screenshots. Every component of information design, whether textual or visual, should play a role in communicating concepts to the user. If a component does not convey a concept, then the component adds to the processing burden for the user without bringing any extra understanding. Essentially, decorative components reduce communication effectiveness.

Avoid special graphic effects for the following reasons:

  • Any non-essential visual or textual information can distract a user, or even confuse a user.
  • Screenshots should appear as close as possible to what the user really sees on-screen. There are no drop-shadows around windows on-screen.
  • Drop-shadows as pure decoration please some people. Others might see such decoration as an attempt to glamorize a dull topic.
  • Many icons use drop-shadows. You might want to include screenshots of these icons in the documentation. If you add drop-shadows to your application screenshots, you risk devaluing drop-shadows on icons. Also, the use of drop-shadows for different purposes can confuse the user.

10.5.  Using Callouts

This section discusses the use of callouts with screenshots.

10.5.1. When to Use Callouts

Use callouts to graphically identify key features. Do not use callouts to give instructions such as "Click here to close the window". Instead, identify the feature and give the instructions in text. The following figure shows a screenshot that uses callouts to graphically identify key features.

Figure 10-1 Sample Screenshot with Callouts

10.5.2. Callout Text

Use the GIMP Dynamic Text plugin to create callout text. The features of the Dynamic Text plugin make localization of the callout text easier. For example, a translator can double-click on callout text to open the Dynamic Text dialog, then paste in the translated text. For more information on the Dynamic Text plugin, see the entry in the GIMP Plugin Registry.

Ensure that you leave sufficient space around callout text to allow for the expansion of the text after translation.

Use sentence capitalization rules in the callout text. Terms that normally take initial capitals are exceptions to this rule.

10.5.3.  Callout Lines

Use straight horizontal lines and vertical lines only. Do not draw lines at an oblique angle to the screenshot. Due to the limitations of raster formats such as PNG, lines drawn at an oblique angle to the screenshot appear jagged. Beware that straight callout lines might not be very clear if they are parallel and close to lines in the window display that represent edges of window elements.

Keep callout lines as simple as possible. Try to restrict the callout line to one straight line. Where possible, do not create a perpendicular angle on the callout line that leads into the text.

Do not create callout lines that fold back on themselves. If a callout line must be more complex than one straight line, ensure that the callout flows in one direction. The following figure is an example of callout lines not flowing in one direction:

Figure 10-2 Callout Lines Flowing in More Than One Direction

Use the pencil tool to draw callout lines. Do not use the Gfig plugin. The pencil tool is easier to use and gives you more precise, close control. When you use the Gfig plugin, you might have difficulty in ensuring that the lines are drawn at consistent angles to the image.

10.6. Text Equivalents for Screenshots

For information about writing text equivalents for graphics, see Chapter 9 ― Writing Accessible Documentation.

10.7. When to Use Screenshots

For guidelines about when to use screenshots in online Help and printed manuals, see Chapter 2 ― Basic Building Blocks of Information Design.

11. Legal Topics

This chapter provides guidelines on how to use trademarks in GNOME documentation.

11.1. Trademarks

Avoid using trademarked terms in free software documentation.

11.2. Copyrights

You must place the copyright notice in a manner and location that gives reasonable notice to the claim of copyright. In GNOME documentation, always use the front matter page for the copyright notice. See the front matter page of this style guide for an example of the appropriate way to assign copyrights.

11.2.1. Use of the Copyright Word and the Copyright Symbol

The front matter sections in templates for GNOME documentation are set up to generate both the word Copyright, and the copyright symbol ©. Although the use of both the copyright word and the copyright symbol together is not required in the USA and in many other countries, you should include both in GNOME documentation for the following reasons:

  1. There are no formal copyright notice requirements in the Berne Convention.
  2. The Universal Copyright Convention (UCC) states that any formality in a national law may be satisfied by placing a copyright notice consisting of © [copyright date] [copyright owner]. Therefore, although the notice Copyright © [copyright date] [copyright owner] might be redundant in jurisdictions that are members of the Berne Convention and the UCC, this is the notice that provides the most copyright coverage worldwide.
  3. The use of the word Copyright spelled out is also helpful in the case where the © symbol cannot be displayed. This is particularly helpful when the work on which the notice is affixed is in electronic form.

11.2.2. Copyrights for Multiple Authors

Assign a general copyright to each author in the front matter page. You do not need to add a separate copyright page for each section that each individual author provides. To credit authors for specific contributions to different parts of a book, you can add an author list as an appendix to your book. See Appendix E ― GDSG Contributors in this book for an example of an author list as an appendix.

11.3. Applying the GFDL

Familiarize yourself with the http://www.gnu.org/licenses/fdl.html (GFDL). All GNOME documentation is published under the GFDL. A free software license allows you to use and modify information published under that license.

11.4. History

A history section is mandatory for all documents released under the GFDL, even if you are writing a new manual. You must retain history data from previous versions of any manual that you modify. See the About This Document page of this guide for an example of the appropriate way to record history information.

11.5. Acknowledgements

You only need to include a section for acknowledgements if you have acknowledgement data. You must retain acknowledgements from any GFDL-licensed documentation from which you draw information, in an Acknowledgements section. Under the terms of the GFDL, you must also include copyrights in your manual for any GFDL-licensed documentation from which you draw information. However, in the context of the GNOME project, you can contact copyright holders for source documentation and ask if they are willing to waive their copyrights in the manual that you are writing. If authors of source documentation do waive their copyrights for your manual, you must still acknowledge your sources in the Acknowledgements section.

A. Recommended Terminology

This appendix contains a glossary of terms for use in GNOME documentation. The terms are listed in the following categories:

A.1. Introduction

The glossary provides the following information for each term, where relevant:

Definition

A definition of the term in the context of the GNOME Desktop. If the term applies only to a specific type of documentation, the type of documentation is noted after the definition, in brackets. For example, [System administration documentation].

Usage

Grammatical and syntax guidelines for authors about how to use the term.

Tags

Guidelines for tag usage.

Example

One or more examples to illustrate how to use the term.

Note

Additional information such as exceptions, synonyms, and so on.

In general, terms that are listed in the American Heritage Dictionary do not appear in this glossary. However, if the definition in the American Heritage Dictionary is not clear enough, or if there is a specific variation of a term is used in the GNOME Desktop, the term appears in this glossary.

To suggest a term for inclusion in this glossary, send your request to .

A.2. GNOME Desktop Terms

This section contains terms that you use when you describe the user interface of the GNOME Desktop, with the exception of buttons.

applet

Definition: A small application that resides on a panel. Applets usually have a simple user interface.
Usage: Normal text rules.
Tags: Prose tag rules. Use the application tag for the names of applets.
Example: Each applet has a simple user interface that you can operate with the mouse or keyboard.
Note: If you think that the term applet might be confusing in a particular context, use the more specific term panel applet.

applet popup menu

Definition: The popup menu that opens when you right-click on the handle of an applet, or on any blank area in an applet. Applet popup menus typically contain the following items:
  • Preferences
  • Help
  • Remove From Panel
  • Move
The applet popup menu can also contain applet-specific items.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Right-click on the Command Line applet to open the applet popup menu.

application registry [System administration documentation]

Definition: The application registry is a location that contains text files that register applications.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The application registry for the GNOME Desktop is located in the /usr/share/gnome/application-registry directory.

assistant

Definition: An interactive tool that helps you to perform a complex task. An assistant guides you through the steps required to perform the task. For example, the Evolution Setup Assistant guides you through the initial configuration process for the Evolution email client.
Usage: Normal text rules. Use title capitalization for assistant names.
Tags: Prose tag rules. Use the application tag for the name of an assistant.
Example 1: You can use an assistant to configure an LDAP server.
Example 2: Click on the Forward button on the Evolution Setup Assistant.
Note:

Do not use the following terms as synonyms for assistant:

  • Druid
  • Wizard

auto, prefix

Definition: A prefix that describes an action where the system does something for you to save you effort.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Autohide, autocomplete.
Note: Do not hyphenate this prefix, or use the prefix as a separate word. For example do not use auto-complete, auto hide, and so on.

autocomplete

Definition: To automatically complete a path or command name as you type. The Location field in a Nautilus window includes an autocomplete function.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The Command Line applet contains a history-based autocompletion function.
Note: Do not hyphenate this term, do not use auto-complete.

autogravity

Definition: A feature that enables your windows to expand automatically in the most suitable direction for display on your screen. Autogravity prevents your windows from expanding off your screen. Autogravity affects window display when a window expands as a result of a system action. For example, if you click on a tabbed section in a dialog, and the new tabbed section requires more space, then autogravity can control how the window expands.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Autogravity does not affect window display when you maximize a window.
Note: Do not hyphenate this term, do not use auto-gravity.

autohide

Definition: To automatically hide a user interface item when the item is not in use.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To set your panel to autohide, modify the properties of the panel.
Note: Do not hyphenate this term, do not use auto-hide.

autoindent

Definition: To automatically indent text to the same tab stop position as the previous line in a file.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The gedit text editor contains an autoindent function.
Note: Do not hyphenate this term, do not use auto-indent.

backtrace

Definition: A text representation that details the current hierarchy of functions being called by an application. If an application crashes, you can use the backtrace to identify what code was being executed when the application crashed.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Bug Buddy automatically adds the core file or backtrace to the bug report.
Note: Spell as one word, and do not hyphenate. Do not use back trace or back-trace.

border

Definition: The border around a window. The titlebar and the border of a window are the components of the window frame.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select this option to include the titlebar and border of a window in a screenshot.
Note: Do not use the term edge as a synonym for border.

button

Definition: A user interface element that you use to start an action. There are many types of button in the GNOME Desktop. For more information about the types of button and the rules for their usage, see Section A.3 ― Buttons in the GNOME Desktop. Some buttons do not have labels, so you do not have a convenient reference term. Although a button does not have a name, there might be a tooltip for the button. If the text in the tooltip is appropriate, use that text as the button name.
Usage: See Section A.3 ― Buttons in the GNOME Desktop.
Tags: Use the guibutton tag for button names.
Example: The History button is a feature of the Command Line applet.
Note: When you refer to a button that has a specific identity but no textual label, use title capitalization for the button name.

check box

Definition: A dialog element that you use to select or deselect an option.
Usage: Normal text rules.
  • Verb: Select, deselect, or choose, depending on the function that the check box fulfills.
  • Noun: Option.
Tags: Use the guilabel tag for the check box name.
Example: Select the Create monochrome image option to create a screenshot in black and white.
Note:

Spell as two words, do not use checkbox.

Avoid using the term check box in your documentation. Use the term option instead.

color selector dialog

Definition: A dialog that you use to select a color. When you click on a color selector button the color selector dialog is displayed.
Usage: Normal text rules.
Tag: Prose tag rules.
Example: Click on the Color to use button to display the color selector dialog.
Note: Color selector dialog is a generic term for the dialog that is displayed when you click on a color selector button.

color wheel

Definition: The circular control on a color selector dialog that enables you to choose a color.
Usage: Normal text rules.
Tag: Prose tag rules.
Example: On the color selector dialog, use the color wheel or sliders to choose the color.

column heading

Definition: A heading for a table column in a dialog or window. Some column headings exhibit button-like behavior. For example, to sort the data in the Evolution Inbox, click on the heading of the column by which you want to sort the data.
Usage: Normal text rules.
  • Verb Phrase: Click on.
  • Noun: Column heading.
Tags:

Prose tag rules.

Use the guilabel tag for the names of column headings.

Example: To sort the file types by filename extension, click on the Extension column heading.

combo box

Do not use this term. Use the term drop-down combination box.

compose keyboard

Definition: A compose keyboard is an onscreen keyboard that contains alphanumeric keys. You can use a compose keyboard to compose text by activating the keys on the keyboard.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The GOK compose keyboard is a standard alphanumeric keyboard.

control

Definition: An instrument that you use to operate or guide the user interface. For example, radio buttons, sliders, check boxes, and so on are controls.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The controls theme option affects the appearance of controls in dialogs and applets.
Note 1: In user documentation, do not use widget as a synonym for control.
Note 2: Some controls reside in dialogs and in this situation you can refer to the controls as dialog elements or controls, depending on the context in which you are describing the controls.
Note 3: See also dialog element.

criterion

Definition: A condition that is applied to an advanced search, a filter, or a virtual folder in Evolution Inbox. Advanced searches, filters, and virtual folders test for criteria that you specify. For example, you can create an advanced search to find messages from a particular address that contain particular text. To do this, you create an advanced search with two criteria. One criterion specifies the address of the sender, the other criterion specifies the text.
Usage: Normal text rules.
Tags: Prose tag rules.
Example 1: To add a criterion to the advanced search, click on the Add button.
Example 2: You can also perform advanced searches that use more complex search criteria.
Note 1: The plural of criterion is criteria. Do not use criteria to express the singular form of this noun.
Note 2: Do not use rule or condition as synonyms for criterion.

current viewport

Definition: The viewport that is displayed on the GNOME Desktop.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The current viewport is highlighted with a checked background.

current workspace

Definition: The workspace that is displayed on the GNOME Desktop.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: On the Workspace Switcher applet, the button that represents the current workspace is pressed in.

desktop

Definition: The part of the GNOME Desktop where there are no interface graphical items, such as panels and windows.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Right-click on the desktop to open the Desktop menu.
Note 1: Use desktop in the user interface, in Help, and in documentation body text.
Note 2: See also desktop background, desktop environment, GNOME Desktop.

desktop background

Definition: The image or color that is applied to the desktop.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To change the desktop background, right-click on the desktop, then choose Change Desktop Background from the Desktop menu.
Note 1: Use desktop background in the user interface, in Help, and in documentation body text.
Note 2: See also desktop, desktop environment, GNOME Desktop.

desktop environment

Definition: The totality of the following:
  • All windows, panels, and workspaces.
  • All libraries, applications, protocols, and so on that the GNOME Desktop uses.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Choose the GNOME Desktop from the list of available desktop environments.
Note 1: The term desktop environment is used mostly, but not exclusively, in system administrator documentation and developer documentation.
Note 2: See also desktop, desktop background, GNOME Desktop.

Desktop menu

Definition: A menu that you can use to arrange items on your desktop.
Usage: Title capitalization for the term Desktop, lowercase letters for the term menu.
Tags: Use the guimenu tag for the term Desktop.
Example: Right-click on the desktop to open the Desktop menu.
Note: Use desktop in the user interface, in Help, and in documentation body text.

desktop object

Definition: An icon on your desktop that you can use to open your files, folders, and applications.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can use desktop objects to provide convenient access to files, folders, and applications that you use frequently.

desktop entry file [System administration documentation]

Definition: A data file that provides information about an item in a menu, a panel launcher, or a desktop object. Desktop entry files have a .desktop file extension.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The desktop entry file contains keywords which determine the location of the item in the menu hierarchy.

dialog

Definition: A popup window in which the user enters information or commands.
Usage:

Normal text rules.

Apply title capitalization to the name of a dialog.

Tags: Use the guilabel tag for the dialog name.
Example: Use the Panel Properties dialog to specify the color and image for the panel background.
Note 1: Do not use dialog box.
Note 2: Some dialogs in the GNOME Desktop do not have a title. If the dialog does not have a title, you can assign the dialog an appropriate title in your documentation.

dialog element

Definition: A component part of a dialog. Examples of dialog elements are: check boxes, command buttons, tabs, and tabbed sections.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The Background tabbed section contains the following dialog elements.
Note: You can shorten dialog element to element when you are clearly referring to a dialog element.

dialog pane

Definition: An area in an application window that resembles a dialog, and where you enter data.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Enter the information for the submenu in the Basic tabbed section on the dialog pane.

directory entry file [System administration documentation]

Definition: A data file that provides information about a menu. Directory entry files have a .directory file extension.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The directory entry file specifies the details for the menu, such as a name, a tooltip, and an icon.

drawer

Definition: A collapsible extension of a panel.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can move objects between panels and drawers.

drop-down combination box

Definition: A text box with a drop-down list attached. You can either type a value, or choose a value from the list.
Usage:

Normal text rules.

  • Verb Phrase: Use the drop-down-name drop-down combination box to specify.
  • Noun: Drop-down combination box.
Tags:

Prose tag rules.

Use the guilabel tag for the name of a drop-down combination box.

Example: Use the Directory to save images in drop-down combination box to specify the directory in which to save your images.
Note: Do not use the term combo box.

drop-down list

Definition: A dialog element that you use to select one of several items. A drop-down list has a drop-down button that you use to display the available items.
Usage: Normal text rules.
  • Verb Phrase: Use the drop-down-list-name drop-down list to specify.
  • Noun: Drop-down list.
Tags:

Prose tag rules.

Use the guilabel tag for the name of a drop-down list.

Example: Use the Panel size drop-down list to specify the size of the panel.
Note: You cannot type in a drop-down list.

drop-down section

Definition: A dialog element that you use to display additional dialog elements. You click on the associated text to display the additional items.
Usage: Normal text rules.
  • Verb Phrase: Click on.
  • Noun: Drop-down section.
Tags: Use the guilabel tag for the name of a drop-down section.
Example: Use the Save in folder drop-down list, or click on the Browse for other folders drop-down section, to specify the location of the saved image.

emblem

Definition: A small icon that you can add to an item in a Nautilus window.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To add an emblem to an item, drag the emblem to the item.

field

Definition: A dialog element into which you must enter data according to a particular syntax or structure. This includes the following:
  • Elements where you must enter a command, or command line-type information in the element.
  • Elements where the data is part of a database.
Usage: Normal text rules.
  • Verb: Enter.
  • Noun: Field.
Tags:

Prose tag rules.

Use the guilabel tag for the field name.

Example: Enter a command in the Command Line entry field.
Note 1: Do not use the term field to refer to an element in a dialog, unless that element is a field as defined above. Instead, refer to the element by control type, that is, text box, spin box, drop-down combination box, and so on.
Note 2: You can add a qualifier to the term field to help the reader to understand the nature of the field. For example, you might refer to a field as a data field or as an entry field. This can be useful particularly if the field does not have a label.

file content sniffer [System administration documentation]

Definition: A file content sniffer specifies a pattern to search for in a file, and associates the pattern with a MIME type. If a match for the pattern is found, the MIME type associated with the pattern is the MIME type of the file.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: File content sniffers are specified in the file /usr/gnome/etc/gnome-vfs-mime-magic.

filename

Definition:

The name of a file as stored in a directory on a disk.

The term filename can also represent a real filename. For example, when you give an example of a filename in a command.

Usage: Normal text rules.
Tags:

Prose tag rules for the term filename.

Use the filename tag for filenames.

Use the replaceable tag on the term filename when filename represents any filename. See Example 2 below.
Example 1: Use the Image filename text box to specify the filename of the image.
Example 2: Choose Files ▸ filename to view the file, where filename is the name of the file.

flag

Definition: In an email client application, a feature that you can add to a message to specify an action for the message, and a due date and due time for the action. In Evolution, flags are displayed at the top of messages.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use flags to remind yourself to follow up on issues that arise from your messages.
Note: Do not use follow-up flag as a synonym for flag.

flip

Definition: To switch to another workspace or viewport on screen by moving a window or the mouse pointer to the edge of the screen.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use the spin box to specify the delay in milliseconds from the time you touch the edge of the screen with the mouse pointer to when you flip to another workspace or viewport.
Note: Use this term specifically to describe the act of flipping and not as a synonym for switch.

focus

Definition: The state in which an interface component can receive both keyboard input and mouse input.
Usage:

Normal text rules.

Use the following verbs with focus:

  • Give focus.
  • Receive focus.
  • Have focus.
Tags: Prose tag rules.
Example: You can configure how to switch focus from one window to another.
Note: Only one window or control can have focus at any one time. The window that has focus is normally indicated by a highlighted label or titlebar. Objects within a focused window, such as dialog elements, tabbed sections, and buttons, can also have focus. The user or application can set the focus.

folderbar

Definition: The bar at the top of a File Roller window that enables you to navigate through folders within an archive.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: File Roller displays the folderbar only in folder view.

font selector dialog

Definition: A dialog that you use to select a font. When you click on a font selector button, the font selector dialog is displayed.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Click on the font selector button to display the font selector dialog.
Note: Font selector dialog is a generic term for the dialog that is displayed when you click on a font selector button. Do not use this term to refer to the Font Selector application.

GConf [System administration documentation]

Definition:

The user preference management system for the GNOME Desktop. GConf contains the following components:

  • A repository of user preferences
  • A daemon
  • A command line tool

All GNOME Desktop applications store preferences in the GConf repository.
Usage: Initial capitals for GC, normal text rules for onf.
Tags: Use the application tag for the term GConf.
Example: GConf makes user preferences more manageable for system administrators.
Note: Do not use Gconf, gconf, or any other term.

GConf configuration source [System administration documentation]

Definition: A storage location in the GConf repository.
Usage: Normal text rules.
Tags:

Use the application tag for the term GConf.

Use prose tag rules for the term configuration source.
Example: GConf reads the configuration sources in the order specified in the GConf path file.
Note: You can shorten GConf configuration source to configuration source when you are clearly referring to the GConf configuration source.

GConf path file [System administration documentation]

Definition: The file that lists the configuration sources for GConf to search, and the order in which to search the configuration sources.
Usage: Normal text rules.
Tags:

Use the application tag for the term GConf.

Use prose tag rules for the term path file.
Example: Each user has a GConf path file.
Note: You can shorten GConf path file to path file when you are clearly referring to the GConf path file.

GConf preference key [System administration documentation]

Definition: An element in the GConf repository that corresponds to a preference.
Usage: Normal text rules.
Tags:

Use the application tag for the term GConf.

Use prose tag rules for the term preference key.

Use the literal tag for the name of a preference key.

Example: The /apps/gnome-session/options/show_splash_screen preference key corresponds to the Show splash screen on login option in the Sessions preference tool.
Note: You can shorten GConf preference key to preference key when you are clearly referring to the GConf preference key.

GConf repository [System administration documentation]

Definition: A collection of key-value pairs, in a hierarchical file system structure, that represent user preferences.
Usage: Normal text rules.
Tags:

Use the application tag for the term GConf.

Use prose tag rules for the term repository.
Example: The GConf repository is structured as a simple hierarchical file system.
Note: You can shorten GConf repository to repository when you are clearly referring to the GConf repository.

GConf schema [System administration documentation]

Definition: A collective term for a GConf schema key and a GConf schema object.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Typically, GConf schemas are stored in the default configuration source.
Note: You can shorten GConf schema to schema when you are clearly referring to the GConf schema.

GConf schema definition file [System administration documentation]

Definition: A file that lists the keys in a particular application and defines the characteristics of the keys. Typically, schema definition files have a .schemas filename extension.
Usage: Normal text rules.
Tags:

Prose tag rules.

Use the filename tag for the name of a schema definition file.

Example: Schemas are generated from schema definition files.
Note: You can shorten GConf schema definition file to schema definition file when you are clearly referring to the GConf schema definition file.

GConf schema key [System administration documentation]

Definition: A key that stores a schema object for a preference key.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The /schemas/desktop/gnome/interface/font_name key is a schema key for the /desktop/gnome/interface/font_name preference key.
Note: You can shorten GConf schema key to schema key when you are clearly referring to the GConf schema key.

GConf schema object [System administration documentation]

Definition: An element in a configuration source that contains information about a preference key. The schema object contains information such as a suggested value for the preference key, and documentation on the preference key.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: If the value of the schema key is a schema object, return the suggested value from the schema object.
Note: You can shorten GConf schema object to schema object when you are clearly referring to the GConf schema object.

GNOME

Definition: GNU Network Object Model Environment.
Usage: All uppercase letters at all times.
Tags: Prose tag rules.
Example: The GNOME Desktop offers many user-configurable features.
Note: If you refer to an interface element that has Gnome in title capitalization, you still write the term in all uppercase letters.

GNOME Desktop

Definition: The totality of all windows, panels, and workspaces.
Usage: All uppercase letters for GNOME. Initial uppercase letter for the term Desktop.
Tags: Prose tag rules.
Example: GNOME 2.4 Desktop User Guide.
Note 1: Always use GNOME in this context, that is, do not use Desktop as a shortened form of GNOME Desktop.
Note 2: You can include the version number of GNOME after the word GNOME.
Note 3: Use GNOME Desktop in the user interface, in Help, in documentation body text, for marketing purposes, book titles, and references to the product.
Note 4: See also desktop, desktop background, desktop environment.

GNOME footprint

Do not use this term. When you want to refer to the stylized footprint logo, use GNOME logo. When you want to refer to the footprint icon that represents the Main Menu, use Main Menu button.

group box

Definition: A box, in a dialog, that groups a set of related dialog elements.
Usage: Normal text rules.
  • Verb: None.
  • Noun: Group.
Tags:

Prose tag rules for the term group.

Use the guilabel tag for group box names.

Example: To enable autohide, select the Autohide option in the Hiding group.
Note: If you need to be very clear about the location of a dialog element, you can also identify the group that the element resides in.

handle, noun

Definition: A vertical bar that you use to move an object. For example, in gedit the menubar and toolbar have a handle on the left side. You can use this handle to move the menubar and toolbar to a different location in the GNOME Desktop.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select this option to add a handle to the menubar. Grab the handle and drag the menubar to any location in the GNOME Desktop.
Note: The vertical bar at the left side of some applets is a handle. You can use the bar to move the applet. Therefore, refer to the bar as a handle.

handle, verb

Do not use this term. Use another verb appropriate to the context, for example, process, manage, and so on.

hover

Do not use this term. Use the term point to.

icon selector dialog

Definition: A dialog that you use to select an icon. When you click on an icon selector button the icon selector dialog is displayed.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Click on the Normal tile icon selector button to display the icon selector dialog.
Note: Icon selector dialog is a generic term for the dialog that is displayed when you click on an icon selector button.

keymap

Definition: A group of shortcuts. A keymap can contain shortcuts that are active throughout the GNOME Desktop, or shortcuts that are only active for a particular interface item.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can use the Sawfish preference tool to view, add, edit, or delete shortcuts from keymaps.

launcher

Definition:

An item that starts an application or executes a command when you click on the item. You can find launchers in the following places in the GNOME Desktop:

  • Panels: On panels, launchers are represented by icons.
  • Menus: On menus, launchers are represented by menu items.
  • Desktop: On the desktop, launchers are represented by icons.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The properties of a launcher include the name of the launcher, the icon that represents the launcher, and how the launcher runs.

layer

Definition: The GNOME Desktop is structured as a sequence of layers. Each user interface item, such as a window or a panel, is a member of a layer. Each layer has a layer number. A layer number is an integer that represents the position of a layer in the stacking order. Items with a higher layer number always appear above items with a lower layer number. For example, a panel in layer four always appears above a window in layer zero.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select this option to bring windows to the top of the stacking order within the layer when they are unshaded.

list box

Definition: A dialog element that you use to select one of several items. A list box has no drop-down feature.
Usage: Normal text rules.
  • Verb: Select or choose, depending on the function that the list box fulfills.
  • Noun: List box.
Tags:

Prose tag rules for the term list box.

Use the guilabel tag for the list box name.

Example: Select the keymaps you require from the Keymaps list box.

location bar

Definition: A bar that contains elements whose primary function is to enable you to change your location. For example, the location bar on a Nautilus window contains a Location field, zoom buttons, and a View as drop-down list.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To view a website or an FTP site, type the URL for the site in the field on the location bar, then press Return.

Main Menu

Definition: A fixed menu that you can open from various places in the GNOME Desktop, including shortcut keys and the Main Menu button.
Usage: Title capitalization.
Tags: Use the guimenu tag.
Example: To open the Main Menu, click on the Main Menu button.

Main Menu button

Definition: A button that opens the Main Menu. The default appearance of the Main Menu button in panels and menus is a stylized footprint icon.
Usage: Title capitalization for the term Main Menu, all lowercase letters for the term button.
Tags:

Use the guibutton tag on the term Main Menu.

Prose tag rules for the term button.

Example: To open the Main Menu, click on the Main Menu button.

maximize

Definition: To enlarge a window to fill the GNOME Desktop to the maximum area allowed, constrained by other GNOME Desktop elements such as panels. You can maximize windows vertically, horizontally, or both.
Usage: Normal text rules.
Tags:
  • Verb: Prose tag rules.
  • Button: Use the guibutton tag for the Maximize button.
Example: To maximize a window, click on the Maximize button.
Note: Do not use fill as a synonym for maximize.

menubar

Definition: The bar at the top of a window that contains the menus for an application.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The menubar on the Calculator window contains the Calculator, Edit, and Help menus.
Note: Spell as one word, do not use menu bar.

menu item

Definition: An item that you can choose from a menu.
Usage: Normal text rules.
Tags:

Prose tag rules for the term menu item.

Use the menuitem tag when you refer to a menu item name.

Example: The File menu contains the Print menu item.
Note: If necessary, use item in a menu to avoid any ambiguity.

menu item popup menu

Definition:

A popup menu that opens when you right-click on a launcher in a menu. The menu item popup menu contains commands such as the following:

  • Add this launcher to panel
  • Remove this item
  • Properties
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To open the menu item popup menu for Calculator, choose Applications ▸ Accessories, then right-click on Calculator.

Menu Panel

Definition: The panel that stretches the full width of the top edge of the GNOME Desktop. The Menu Panel includes textual rather than graphical menus.
Usage: Title capitalization.
Tags: Prose tag rules.
Example: Unlike other types of panel, you can only have one Menu Panel at a time on the GNOME Desktop.

MIME information file [System administration documentation]

Definition: A MIME information file is a text file that associates MIME types with filename extensions and filename patterns. MIME information files have a .mime file extension.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: In MIME information files, the filename pattern to search for is written as a regular expression.

MIME keys file [System administration documentation]

Definition: A MIME keys file provides information about a MIME type that is used in the user interface. For example, the MIME keys file specifies an icon to represent files of that MIME type. MIME keys files have a .keys file extension.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You must indent the keys in a MIME keys file with a tab character (\t).

MIME type registry [System administration documentation]

Definition: The MIME type registry is a location that contains text files that register MIME types for the GNOME Desktop.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The MIME type registry for the GNOME Desktop is located in the /usr/gnome/share/mime-info directory.

minimize

Definition: To remove a window from the display without closing the window. You can restore a minimized window to your display in the following ways:
  • Click on the button that represents the window on the Window List applet.
  • Click on the window list icon at the extreme right of the Menu Panel, then select the window name from the window list.
  • Use shortcut keys to switch between windows. To restore a window, release the keys.
Usage: Normal text rules.
Tags:
  • Verb: Prose tag rules.
  • Button: Use the guibutton tag for the Minimize button.
Example: To minimize a window, click on the Minimize button.

native viewport

Definition: The viewport where a minimized window was displayed before it was minimized.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: If this option is not selected, minimized windows restore to their native viewport.

native workspace

Definition: The workspace where a minimized window was displayed before it was minimized.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: If this option is not selected, minimized windows restore to their native workspace.

option

Definition: A function or parameter that you can select in a dialog. An option can be either on or off. An option is usually represented by a check box.
Usage: Normal text rules.
Tags:

Prose tag rules for the term option.

Use the guilabel tag for the name of the option.

Example: Select the Create monochrome image option to capture a black-and-white screenshot.

panel

Definition: An area on the GNOME Desktop from which you can run applications and applets.
Usage: The following rules apply:
  • When the panel is a specific user interface component, then write the term with an initial uppercase letter. For example, Menu Panel.
  • When the panel is a type of user interface component, then write the term according to normal text rules.
Tags: Prose tag rules.
Example: Panels are areas on the GNOME Desktop from which you can access all of your system applications and menus.

panel object

Definition: An object that resides on a panel.
Usage: Normal text rules.
Tags: Prose tag rules.
Example 1: You can move panel objects in the following ways:
  • From one location to another within a panel.
  • From one panel to another panel.
You can also move objects between panels and drawers.
Example 2: Click on the Run panel object.
Note: You can shorten panel object to object where the meaning is not ambiguous. Also, you do not always need to add the modifier panel object when you write about launchers, menus, applets, and drawers. You can write "click on the Terminal launcher", and so on. However, when you write about other panel objects, such as the Log Out button and the Lock button, specify that the item is a panel object. The following objects can reside on panels:
  • Launchers
  • Menus
  • Applets
  • Drawers
  • Other panel objects, such as the Log Out button and the Lock button

panel object popup menu

Definition: The menu that appears when you right-click on a panel object. Items that typically appear on panel object popup menus include:
  • Properties
  • Help
  • Remove From Panel
  • Move
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Right-click on a launcher to open the panel object popup menu.

panel popup menu

Definition: The menu that appears when you right-click on a vacant space on a panel. The panel popup menu includes menu items such as Add to Panel, Delete This Panel, New Panel, and so on.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Right-click on a vacant space on a panel to open the panel popup menu.

pattern mask [System administration documentation]

Definition: A pattern mask is a series of hexadecimal characters in a file content sniffer. The pattern mask identifies bits in the pattern to ignore when searching for a pattern in a file.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use a pattern mask to specify bits to ignore in a search pattern.

persistent window group

Definition: A window group that remains in your list of window groups even after you end and restart a session.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can create a persistent window group, and then assign windows to be part of the group.

popup menu

Definition: A menu that opens when you right-click or middle-click on an object. A popup menu usually provides commands that are relevant to the object that you click on.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: If you right-click on a panel, a popup menu opens.
Note: Do not use pop-up menu.

preference tool

Definition: A utility that you can use to specify your GNOME Desktop preferences. For example, you can use the Background preference tool to specify a color for the desktop background. Also, you can use the Mouse preference tool to change your mouse buttons from right-handed to left-handed.
Usage: Normal text rules for the term preference tool. Use title capitalization for the names of preference tools.
Tags: Use the application tag for the names of preference tools.
Example: You can use the Theme preferences tool to select a theme for the GNOME Desktop.
Note: If there is a possibility that the term preference tool might be confusing in a particular context, use the more specific term GNOME Desktop preference tool.

radio button

Definition: A dialog element that you use to select one of several mutually exclusive options.
Usage: Normal text rules.
  • Verb: Use select or choose, depending on the function of the radio button.
  • Noun: Option.
Tags:

Prose tag rules.

Use the guilabel tag for radio button names.

Example: Select the Scale image option to scale the background image to fit the panel background.
Note: Avoid using the term radio button in your documentation. Use the term option instead.

raise

Definition: To bring a window to the top of the stacking order within a layer.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Right-click on the titlebar to raise the window.

Remote Desktop

Definition: A feature that enables you to access the Desktop of another user from your system.
Usage: Title capitalization.
Tags: Prose tag rules.
Example: Use the Remote Desktop feature to view or control the Desktop of another user from your Desktop.
Note 1: To avoid confusion with the term desktop, use title capitalization for this term.
Note 2: See also desktop, desktop background, desktop environment, GNOME Desktop.

restore

Definition: To restore a minimized or maximized window to the dimensions that the window had before you minimized or maximized the window.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To restore a maximized window, click on the Maximize button. To restore a minimized window, click on the button for the window in the Window List applet.
Note: Do not use the following terms as synonyms for restore:
  • Uniconify
  • Unmaximize

roll down

Definition: To restore a rolled-up window to the original dimensions of the window.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To roll down a window, double-click on the titlebar.
Note 1: Do not use the term unshade as a synonym for roll down.
Note 2: See also roll up.

roll up

Definition: To reduce a window so that the body of the window moves into the titlebar. When you roll up a window, only the titlebar of the window is visible.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To roll up a window, double-click on the titlebar.
Note 1: Do not use the term shade as a synonym for roll up.
Note 2: See also roll down.

Root menu

Definition: A menu that you can use to navigate between windows and workspaces.
Usage: Initial uppercase letter for the term Root, all lowercase letters in the term menu.
Tags: Use the guimenu tag for the term Root.
Example: To open the Root menu, middle-click on the desktop.

scrollbar

Definition: A scrollbar is a navigation bar that enables you to move through the contents of a window or list box. A scrollbar appears at the side or bottom of a window or list box. A scrollbar contains an arrow at both ends. You click on the arrows to move through a window or list box. A scrollbar also contains a box that you drag to move through a window or list box.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use the scrollbar to scroll through the contents of the window.

searchbar

Definition: The bar near the top of an Evolution window that you can use to search your messages and other items.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can use the searchbar to search the contents of the messages in your message list.

session

Definition: The current GNOME Desktop session that you are using.
Usage:

Normal text rules.

Use the following terms in relation to session:

  • Log in to a session. Do not use log on to a session.
  • Log outof a session. Do not use log off from a session.

Tags: Prose tag rules.
Example: Click on the Log Out button to log out of a GNOME Desktop session.
Note: You log in to a session. You do not log in to your workstation, system, or workspace.

setting

Definition: A value for an adjustable characteristic of a user interface component. Interactive components such as applications and applets, and objects such as files and folders, have associated controls that you can use to modify adjustable characteristics for the component. For example, the Workspace Switcher Preferences dialog contains a Number of workspaces spin box that you can use to specify the number of workspaces on the GNOME Desktop. A setting is the value to which you set the control. For example, the setting of the Number of workspaces spin box might be 4.
Usage: Normal text rules.
Tags: Prose tag rules.
Example 1: The session manager saves your fonts, background, and mouse settings.
Example 2: The window frame setting for a theme determines the appearance of the frames around windows.
Note: Setting is not a synonym for preference or property.

shade

Definition: To reduce a window so that only the titlebar is visible.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To shade a window, double-click on the titlebar.

shutdown, noun, adjective

Definition: The process of shutting down all processes running on a computer.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The shutdown procedure takes approximately two minutes.
Note 1: Do not use shutdown as a verb.
Note 2: See also shut down.

shut down, verb

Definition: To stop all processes running on a computer.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The Log Out dialog enables you to shut down or reboot your computer.
Note 1: Do not use shut down as a noun or adjective.
Note 2: See also shutdown.

side pane

Definition: The pane on the left side of a Nautilus window. The side pane displays information about the current file or folder. The side pane also enables you to navigate through your files.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To add a note, click on the Notes tab in the side pane.

slider

Definition: A control that you use to set a value in a continuous range of values.
Usage: Normal text rules.
  • Verb Phrase: Use the slider_name slider to specify.
  • Noun: Slider.
Tags: Prose tag rules.
Example: Use the slider to specify the volume level.

spin box

Definition: A dialog element that allows you to either type a numeric value, or scroll through all possible values for the item. A spin box is similar to a text box with up and down arrows.
Usage: Normal text rules.
  • Verb: Use the spin_box_name spin box to specify.
  • Noun: Spin box.
Tags:

Prose tag rules for the term spin box.

Use the guilabel tag for the spin box name.

Example: Use the Number of workspaces spin box to specify the number of workspaces on the GNOME Desktop.

stacking order

Definition: The order in which windows are stacked on top of one another on your screen. The position of a window in the stacking order depends on:
  • The layer of which the window is a member.
  • The position of the window in the order of windows within the layer.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select this option to bring windows to the top of the stacking order within the layer when they are unshaded.

staggered

Definition: Use this term to describe the display of a new window or dialog slightly lower and to the right of the previous window or dialog.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Subsequent dialogs are staggered from the previous dialog.

statusbar

Definition: The bar at the bottom of a window that provides information about the current state of what you are viewing in the window. The statusbar also provides any other contextual information.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The Nautilus statusbar displays status information on the selected file or folder.
Note: Spell as one word, do not use status bar.

stick

Definition: If a window is set to stick, then the window appears in all workspaces that you view. You can use the Window Menu to switch the stick setting on and off.
Usage: Normal text rules.
Tags:

Prose tag rules for the term stick.

Use the guimenuitem tag when you refer to menu items.

Example: To set a window to stick, open the Window Menu, then choose Put on All Workspaces.
Note: Do not use the term sticky.

submenu

Definition: A menu that resides in another menu.
Usage: Normal text rules.
Tags:

Prose tag rules for the term submenu.

Use the guisubmenu tag for the name of a submenu.

Example: When you add an executable file to this folder, the file is added to the File ▸ Scripts submenu.

tab

Definition: The part of a tabbed section that you click on to view the tabbed section.
Usage: Normal text rules.
  • Verb Phrase: Click on.
  • Noun: Tab.
Tags: Prose tag rules for the term tab. Use the guilabel tag for tab names.
Example: To modify panel size, position, and hiding properties, click on the Panel tab.

tabbed pane

Definition: A functional area in the Nautilus side pane. To open a tabbed pane, click on a tab in the side pane.
Usage: Normal text rules for the term tabbed pane. Use title capitalization for the name of a tabbed pane.
Tags:

Prose tag rules for the term tabbed pane.

Use the guilabel tag for the name of a tabbed pane.

Example: Type the note in the Notes tabbed pane.

tabbed section

Definition: A tabbed section is one of multiple logical sections that appear on a dialog. To activate a tabbed section, click on the tab on the tabbed section.
Usage: Normal text rules.
  • Verb: None.
  • Noun: Tabbed section.
Tags:

Prose tag rules for the term tabbed section.

Use the guilabel tag for the name of the tabbed section.

Example: You can use the Advanced tabbed section to add translations of the comment.

table

Definition: An element in a dialog or window that includes rows, columns, and column headings.
Usage: Normal text rules.
Tags:

Prose tag rules for the term table.

Use the guilabel tag for the table name.

Example: Enter the details of the translation in the Name/Comment translations table.

terminal

Definition: A window with a command line.
Usage: Normal text rules.
Tags: Use the application tag for the Terminal application.
Example: Select this option to run the application or command in a terminal.

text box

Definition: A dialog element where you type text.
Usage: Normal text rules.
  • Verb Phrase: Use the text box to specify.
  • Noun: Text box.
Tags:

Prose tag rules for the term text box.

Use the guilabel tag for the text box name.

Example: Use the Tooltip/Name text box to specify a name for the drawer.
Note: Spell as two words, do not use textbox.

theme

Definition: A group of coordinated settings that specify how a part of your interface appears. For example, you can select a default theme for dialog elements.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select a theme from the Available Themes list box.

titlebar

Definition: A bar that appears at the top edge of a window. Typically a titlebar contains the title of the window.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select the Capture WM decorations when grabbing a window option to include the titlebar and border of a window in a screenshot.
Note: Spell as one word, do not use title bar.

toolbar

Definition: A bar that appears below the menubar and contains buttons for the most commonly-used commands.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The Eye of GNOME toolbar contains the following buttons:
  • Open
  • Close
Note: Spell as one word, do not use tool bar.

tree

Definition: A tree is a user interface control that contains sections that you can expand and collapse. A tree usually represents a hierarchical structure. The sections of the tree that you can expand and collapse are indicated by, for example, + and - signs.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To open an item in a tree, click on the + (plus) sign next to the item.

uniconify

Do not use this term. Use the term restore.

unmaximize

Do not use this term. Use the term restore.

unshade

Definition: To restore a shaded window to the unshaded dimensions of the window.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To unshade a window, double-click on the titlebar.

username

Definition:

A combination of letters and numbers that identifies a user to the system.

The term username can also represent a real username. For example, when you give an example of a username in a command.

Usage: Normal text rules.
Tags:

Prose tag rules.

Use the replaceable tag for username when you give an example of a username.

Example 1: The login screen provides fields for you to enter your username and password.
Example 2: To log in to a remote system, use the following command: rlogin -l username systemname

vfolder [System administration documentation]

Definition: A virtual representation of items that reside in a physical location or physical locations on your system. For example, a vfolder might represent the contents of several directories. In terms of menus, a vfolder is a representation, in a menu, of items that might be physically located in several directories.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: In terms of menus in the GNOME Desktop, a vfolder is a representation, in a menu, of items that might be physically located in several directories.
Note 1: Do not use Vfolder, vFolder, or any other term.
Note 2: Use an initial capital for Vfolder when the term appears at the start of a sentence.

viewport

Definition: A subdivision of a workspace.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To move a window or dialog from one workspace to another, middle-click on the viewport for the window or dialog.

view pane

Definition: The pane on the right side of a Nautilus window. Nautilus displays your files and folders in the view pane. When you access a web page, Nautilus displays the page in the view pane.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Display in the view pane the item that you want to bookmark.

virtual desktop

Do not use this term. Use the term workspace.

virtual folder

Definition: A representation, as a folder, of messages that might reside in more than one folder. Virtual folders enable you to view messages that are located in several folders, as if the messages are in one folder.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use virtual folders to organize messages that might belong in more than one folder.
Note: Do not use vfolder as a synonym for an Evolution virtual folder.

wallpaper

Do not use this term. Use the term desktop background.

widget

Do not use this term in user documentation. Use the term control.

window

Definition: A rectangular frame that displays a particular application.
Usage: Normal text rules.
Tags:

Prose tag rules.

Use the guilabel tag for the name of a window.

Example: You can grab the titlebar of a window, then drag the window to a new location.

window frame

Definition: The titlebar and border that appears around windows and dialogs.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use the Theme preference tool to change the theme of your window frames.

window group (1)

Definition: A group of windows. You can use the Sawfish preference tool to configure the GNOME Desktop so that when you minimize one member of the window group, the other windows in the group are also minimized.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Brackets around the title of a window indicate that the window is a member of a window group.
Note: You can shorten window group to group where there is no ambiguity.

window group (2)

Definition: A group of windows in the Window List applet.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To open a list of the members of a window group, click on the button that represents the window group.
Note 1: You can shorten window group to group where there is no ambiguity.
Note 2: The Window List window group bears no relation to the Sawfish window group.

window list

Definition: A list of the windows that are open on your screen. To view your window list, perform one of the following actions:
  • Add the Window List applet to a panel. The Window List applet is an iconic display of your windows. The buttons in your Window List applet represent your windows.
  • Open the Root menu, then choose Windows.
  • Click on the window list icon at the extreme right of the Menu Panel.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use the arrow keys to cycle through the window list.

window list icon

Definition: The icon at the extreme right of the Menu Panel, which you click on to display a list of your open windows.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To give focus to a window, click on the window list icon, then select the window.

Window Menu

Definition: A menu of actions that you can perform on a window. For example, the Metacity Window Menu includes the following menu items: Close, Minimize, Maximize, Shade.
Usage: Title capitalization.
Tags: Use the guimenu tag.
Example: Use the Window Menu to perform actions on your windows.

window name

Definition: The name of a window, which is displayed in the titlebar.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: On the Window List applet, square brackets around the window name indicate that the window is minimized.
Note: Do not use window title as a synonym for window name.

workspace

Definition: A discrete area in which you can work. You can have many workspaces in the GNOME Desktop, and you can switch from one workspace to another. Each workspace can contain different windows or processes. You can only work in one workspace at any time.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use the Number of workspaces spin box to specify the number of workspaces you require.
Note: Do not use virtual desktop as a synonym for workspace.

workspace list

Definition: A list of the workspaces that are in your session. Workspace Switcher displays your workspace list.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Workspace Switcher adds new workspaces to the end of the workspace list.

A.3. Buttons in the GNOME Desktop

This section lists the terms to use when you refer to buttons in the GNOME Desktop.

... button

Definition: A button that you click on to perform an action. This action is usually to display a list of options from which you can choose.
Usage: Normal text rules.
  • Verb Phrase: Click on.
  • Noun: Button. Give directions to the button.
Example: To choose a signal for the window to respond to, click on the button to the right of the Signal field.

arrow button

Definition:

A button that you click on to display more information. Arrow buttons appear in the following locations:

  • Drop-down combination boxes
  • Drop down lists
  • List boxes
  • Scrollbars, at both ends
  • Spin boxes
Usage: Normal text rules.
  • Verb Phrase: Click on.
  • Noun: Arrow button.
Example: To scroll through the list, click on the arrow buttons.
Note: Refer to the buttons on a spin box as arrow buttons. If an arrow button has a function, you can name the button by the function. For example, the History button in the Command Line applet.

color selector button

Definition: A button that you use to choose a color. When you click on a color selector button the color selector dialog is displayed.
Usage:

Normal text rules for the term color selector button. Standard capitalization rules for specific color selector button names.

  • Verb Phrase: Click on.
  • Noun: Button, color selector button. Use the more verbose form where you need to clarify that you are referring to a color selector button.
Tags: Use the guibutton tag with specific color selector button names.
Example: To choose a background color for the panel, click on the Color to use button.

command button

Definition: A button that you use to start an action. Command buttons are always rectangular in shape. Command buttons always have a text label, but the label can also include a graphic.
Usage:

Title capitalization for the command button name.

  • Verb: Click when the button represents a frequently-used command such as OK. Click on when the button represents a GNOME-specific or little-known command.
  • Noun: None. You usually do not need to use a noun to refer to a command button. For example, click OK. If you must use a noun, use button.
Tags: Use the guibutton tag for the command button name.
Example 1: To save your changes and close the dialog, click Close.
Example 2: To delete a translation of a launcher, select the translation then click on the Remove button.

font selector button

Definition: A button that you use to choose a font. When you click on a font selector button the font selector dialog is displayed.
Usage: Normal text rules.
  • Verb Phrase: Click on.
  • Noun: Button, font selector button. Use the more verbose form where you need to clarify that you are referring to a font selector button.
Tags: If you refer to a specific font selector button name, use the guibutton tag for the button name.
Example 1: To choose a font in which to display your gedit documents, click on the Default Font button.
Example 2: To choose a font to in which to display the pronunciation of a word, click on the Pronunciation font selector button.

hide button

Definition: A button that enables you to hide a panel or drawer. You can also use hide buttons to show hidden panels. Hide buttons appear at either end of panels and at one end of open drawers.
Usage: Normal text rules.
  • Verb Phrase: Click on.
  • Noun: Hide button.
Example: Select the Show hide buttons option to display hide buttons on your panels.

icon selector button

Definition: A button that you use to choose an icon. When you click on an icon selector button, the icon selector dialog is displayed.
Tags: If you refer to a specific icon selector button name, use the guibutton tag for the button name.
Usage Normal text rules.
  • Verb Phrase: Click on.
  • Noun: Button, icon selector button. Use the more verbose form where you need to clarify that you are referring to an icon selector button.
Example 1: To choose an icon to represent the application, click on the Icon button.
Example 2: To choose an icon to represent the keyboard map, click on the icon selector button at the right side of the dialog.

Normal Size button

Definition: A button that enables you to change the size of items in a view pane to the normal size. The Normal Size button displays "100%", and appears in the location bar on a Nautilus window.
Usage: Title capitalization for the term Normal Size, all lowercase letters for the term button.
Tags: Use the guibutton tag for the term Normal Size.
Example: To restore the size of items in a view to normal size, click on the Normal Size button.

toggle button

Definition: A button that you use to switch between two states.
Usage:
  • Verb: Select.
  • Noun: Option.
Tags: Use the guibutton tag with the toggle button name.
Example: To show grid lines, select the Visible option.

toolbar button

Definition: A button in an application toolbar. Toolbar buttons are usually shortcuts to functionality that is available in the menus of the application.
Usage: Normal text rules for the term button.
  • Verb Phrase: Click button_name on the toolbar, click on the button_name button.
  • Noun: Button.
Tags: Use the guibutton tag for the toolbar button name.
Example 1: To refresh the contents of the view pane, click on the Reload button.
Example 2: Click Save on the toolbar.

window frame button

Definition: One of the following buttons that reside in a window frame:
  • Window Menu button
  • Minimize button
  • Maximize button
  • Close Window button
Usage:

Normal text rules for the term button.

  • Verb Phrase: Click on.
  • Noun: Button.
Tags: Use the guibutton tag for the window frame button name.
Example: To open the Window Menu, click on the Window Menu button.

window list button

Definition: A button that represents a window in the Window List applet.
Usage:

Normal text rules.

  • Verb Phrase: Click on.
  • Noun: Window list button.
Tags: Prose tag rules.
Example: To restore a window, click on the window list button for the window in the Window List applet.

Zoom In button

Definition: A button that enables you to increase the size of items in a view pane. The Zoom In button displays a plus sign, and appears in the location bar on a Nautilus window.
Usage: Title capitalization for the term Zoom In, all lowercase letters for the term button.
Tags: Use the guibutton tag for the term Zoom In.
Example: To increase the size of items in a view, click on the Zoom In button.

Zoom Out button

Definition: A button that enables you to reduce the size of items in a view pane. The Zoom Out button displays a minus sign, and appears in the location bar on a Nautilus window.
Usage: Title capitalization for the term Zoom Out, all lowercase letters for the term button.
Tags: Use the guibutton tag for the term Zoom Out.
Example: To reduce the size of items in a view, click on the Zoom Out button.

A.4. User Actions

This section defines a list of user actions in the GNOME Desktop.

activate [Accessibility documentation]

Definition: Use this verb to describe the action of clicking on a user interface control, such as a button, when it is not appropriate to use the verb click. For example, use this verb if you are writing instructions for users who are unable to use a mouse.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Activate the applet control that has focus, if applicable.

choose

Definition: To pick a course of action or assign a course of action.
Usage: Normal text rules.
Example 1: Choose Applications ▸ Accessories ▸ Calculator to start the Calculator application.
Example 2: On the Run Application dialog, use the drop-down combination box to choose an application to run.

click on, click

Definition:

Press and release the left mouse button on an item once.

You can differentiate between click on and click as follows:

  • Click on: Use this verb when you refer to most interactive elements in the GNOME Desktop, such as:

    • GNOME-specific buttons.
    • Buttons that represent commands that are not frequently used.
    • All interactive elements other than buttons, such as column headings.

  • Click: Use this verb when you refer to frequently-used command buttons, for example:

    • OK
    • Cancel
    • Save
    • Revert
    • Try
    • Apply
    • Close
    • Help
    • Yes
    • No
    • Find
    • Replace
    • Browse

Usage: Normal text rules.
Example 1: Click OK.
Example 2: To hide a panel, click on one of the hide buttons.

click-and-hold

Definition: Press and hold the left mouse button on an item.
Usage: Normal text rules.
Example: Click-and-hold the left mouse button to initiate the capture area.

close

Definition: To remove a window, dialog, or user interface component from the GNOME Desktop. Use in conjunction with display and open.
Usage: Normal text rules.
Example 1: To close a window, choose File ▸ Close.
Example 2: Click Cancel to close the dialog.
Note: Do not use quit in this context.

collapse

Definition: To close an open item in a tree structure. The Tree tabbed pane in the Nautilus file manager is a tree structure. To collapse a folder in the Tree tabbed pane, click on the arrow next to the folder.
Usage: Normal text rules.
Example: You can expand and collapse the folders in the Tree tabbed pane.

configure

Definition: To set up an application. To configure is typically a larger-scale activity, and usually occurs at installation time.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can configure how PDAs connect to your computer.
Note: See also customize, modify.

customize

Definition: To modify the behavior of an application to suit individual requirements.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To customize a panel, use the Panel preference tool.
Note: See also configure, modify.

delete

Definition: To remove an item permanently.
Usage: Normal text rules.
Example 1: When you delete a file or folder, the file or folder is not moved to Trash, but is deleted from your file system immediately.
Example 2: To delete a panel from the GNOME Desktop, right-click on the panel that you want to delete, then choose Delete This Panel.
Note: Do not use remove to describe the deletion of an item that you cannot add back to the GNOME Desktop.

deselect

Definition: To switch off a behavioral characteristic in a dialog.
Usage: Normal text rules.
Example: Deselect the Display tooltips option to switch off tooltips.
Note:

Do not use unselect when you refer to switching off a binary option.

Do not use deselected for a binary option that is switched off. Use unselected instead.

display

Definition: Use this verb when an item is not already open somewhere in the GNOME Desktop. The item needs to be opened, added, or launched.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To display the Background Preferences dialog, right-click on the desktop, then choose Change Desktop Background.

double-click on

Definition: To press and release the left mouse button on an item twice, in rapid succession.
Usage: Normal text rules.
Example: To start an application from the desktop, double-click on the application launcher.

drag

Definition: To click a mouse button on an object, hold the mouse button, and move the mouse to move the object.
Usage: Normal text rules.
Example: Drag the launcher to the panel.
Note: Avoid using the term drag and drop.

duplicate

Definition: To create an exact copy of an object. The new object is created in the same location as the original object.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select the file or folder that you want to duplicate.
Note: When you duplicate an object, the object is not copied to the clipboard.

enter

Definition:

Use this verb to describe the following:

  • To input data into a text box or field by using a combination of typing from the keyboard, and then either pressing a key or clicking on a button.
  • To either:
    • Type data in a text box, or field.
    • Click on a button and select a value from a predefined list of values
Usage: Normal text rules.
Example 1:

The following example describes a File text box with a Browse button beside it where you can either type the name or click Browse to select a name:

Enter a name for the output file in the File text box.

Example 2: Click on the calculator buttons to enter numbers and mathematical functions.
Note: Where possible, use specify instead of enter.

execute

Definition: Instruct your computer to perform a command.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Execute the following command to list the contents of the directory: ls
Note 1: Execute implies that you type a command at the command line, then press Return. Execute implies a single action that the computer performs.
Note 2: See also run.

exit

Definition: To stop an application from running. Exit implies normal cessation of application activity.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: If you close the last window, the application exits.
Note: See also quit.

expand

Definition: To open a closed item in a tree structure. The Tree tabbed pane in the Nautilus file manager is a tree structure. To expand a folder in the Tree tabbed pane, click on the arrow next to the folder.
Usage: Normal text rules.
Example: You can expand and collapse the folders in the Tree tabbed pane.

grab

Definition: To point to the edge of a window frame, or corner of a window, and click to take hold of the window. After a grab action you usually drag the object.
Usage: Normal text rules.
Example: To resize the window, grab the border and drag the border to the new size.

left-click on

Definition: To press and release the left mouse button on an item once. Use this term when you want to avoid ambiguity when describing an action that also involves a middle-click or a right-click.
Usage: Normal text rules.
Example: You can left-click on the application icons in the Window List applet to maximize and minimize application windows.

log in, verb

Definition: To supply a username and password to gain access to a session.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select this option to display a splash screen when you log in.
Note 1: You log in to a session, not your workstation, system, or workspace.
Note 2: Use log in rather than log on.
Note 3: See also login.

log out, verb

Definition: To terminate a session.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To log out of your session or shut down your system, click on the Log Out button.
Note 1: You log out of a session, not your workstation, system, or workspace.
Note 2: Use log out rather than log off.
Note 3: See also logout.

middle-click on

Definition: To press and release the middle mouse button on an item once.
Usage: Normal text rules.
Example: To move an applet, middle-click on the applet.

middle-click and hold

Definition: To press and hold the middle mouse button on an item.
Usage: Normal text rules.
Example: To move a panel, middle-click and hold, then drag the panel to the new location.

modify

Definition: To change specific parameters in an application. Use this verb to refer to making specific changes to the preferences or properties of an item.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can modify animation preferences for your panels.
Note: See also configure, customize.

open

Definition: To open any user interface component. Examples of items that you can open include:
  • Main Menu
  • Applications menu
  • Desktop Preferences menu
  • Actions menu
  • Root menu
  • Desktop menu
  • Panel popup menu
  • Panel object popup menu
Usage: Normal text rules.
Example: Right-click on a panel object to open the panel object popup menu.

point to

Definition: To position the pointer over a particular object or location without clicking.
Usage: Normal text rules.
Example: When you point to the submenu icon a tooltip appears.
Note: Use point to instead of point at.

press

Definition: Use this verb to describe keyboard input.
Usage: Normal text rules.
Example: Press Return to execute the command.

press-and-hold

Definition: To press one or more keys and hold down the keys. Typically, you press-and-hold keys while you press another key.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Press-and-hold Ctrl+Alt and continue to press Tab to switch the focus between the desktop and the panels.

quit

Definition: To abruptly stop an application, without necessarily completing current tasks. Quit implies a sudden or unexpected cessation of activity.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To quit the application without saving your current project, select Ctrl+Q.
Note: See also exit.

remove

Definition: To remove an item or functionality that you can add back to the GNOME Desktop. When you remove an item the item is not visible to the user. When you remove functionality, the functionality is not active in the GNOME Desktop.
Usage: Normal text rules.
Example 1: To remove an object from a panel, right-click on the object, then choose Remove From Panel.
Example 2: To remove a file type or a service, select the item that you want to remove, then click Remove.
Note: Do not use delete to describe the removal of an item that you can add back to the GNOME Desktop.

right-click on

Definition: To press and release the right mouse button on an item once.
Usage: Normal text rules.
Example: Right-click on any part of a panel to open the panel popup menu.

run

Definition: To change the status of an application, program, or script from continuously inactive to continuously active.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To run the Terminal application, execute the following command: gnome-terminal
Note 1: Run implies a continuous flow of activity.
Note 2: See also execute.

select (1)

Definition: To identify an object as the object on which an action is to be performed. For example, the object can be text, one or more desktop launchers, a folder in the Nautilus Tree tabbed pane, and so on. When you select objects, they usually appear highlighted.
Usage: Normal text rules.
Example: In the Menu Editor window, select the menu to which you want to add a submenu.
Note:

Do not use choose or highlight in this context.

Refer to the text that is selected as the selection, selected text, selected menu, and so on.

select (2)

Definition: To pick an item that assigns a behavioral characteristic, value, or parameter from a predefined value or a predefined set of values.
Usage: Normal text rules.
Example 1: Select the Display tooltips option to display tooltips when you start a GNOME session.
Example 2: To change the size of the panel, select a size from the Panel size drop-down list.
Note: Do not use select to describe more complex methods of inputting information. Use specify instead.

selected/unselected

Definition: Use these terms to describe the on or off state of a binary choice in a dialog.
Usage: Normal text rules.
Example: The default state of the Display tooltips option is unselected.
Note:

Do not use deselected for a binary option that is switched off.

Do not use unselect when you refer to switching off a binary option. Use deselect instead.

show

Definition: Use this verb when an item is already open somewhere in the GNOME Desktop, but hidden.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To show more options, click on the More Options button.

specify

Definition: Use the verb specify to describe more complex methods of inputting information. Use specify when referring to a dialog element such as a drop-down combination box, spin box, slider, text box.
Usage: Normal text rules.
Example: Use the Minimum size spin box to specify the minimum width of the window list buttons.
Note: Do not use specify with simpler dialog elements such as check boxes and radio buttons. Use select instead.

start

Definition: To open an application.
Usage: Normal text rules.
Example: To start Calculator, choose Applications ▸ Accessories ▸ Calculator.
Note: Do not use the terms open or run in this context.

terminate

Definition: To stop a system process permanently.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To terminate a process, choose File ▸ Kill Process.
Note: Do not use kill except where quoting the user interface.

triple-click on

Definition: Press and release the left mouse button on an item three times in rapid succession.
Usage: Normal text rules.
Example: To select a line at a time, triple-click on the first line that you want to select and drag the mouse to the last line that you want to select.

type

Definition: To type text from the keyboard.
Usage: Normal text rules.
Example 1: Type the content of the document in the gedit window.
Example 2: Type man ghex at the command line prompt and press Return.
Example 3: Type a name for the drawer in the Tooltip Name text box.

A.5. General Computer Terms

This section contains general computer terms that are not specific to the GNOME Desktop.

3D

Definition: Abbreviation for three-dimensional.
Usage: Normal text rules.
Example: Select this option to display a 3D beveled border around the full-screen view of an image.
Note: Do not use 3-D, 3d, or any other term.

accelerator key

Do not use this term. Use the term shortcut key.

access keys

Definition: Keys that enable you to perform an action from the keyboard rather than using the mouse to choose a command from a menu or dialog. Each access key is identified by an underlined letter on a menu or dialog option. In some cases, you must press the Alt key in combination with the access key to perform the action.
Usage:
  1. Normal text rules.
  2. Avoid using the terms access key or access keys in text instructions, if the context is clear.
  3. Use the term access key as a qualifier for the key name.
Tags:

Use the keycap tag for key names.

Use the keycombo tag for key combinations.

Example: To open a new file, press Alt+F. When the File menu opens, press the access key N.
Note: Do not use mnemonic as a synonym for access key.

Alt

Definition: The Alt key on the keyboard.
Usage: Title capitalization.
Tags: Use the keycap tag.
Example: Use the default shortcut keys Alt+F1 to open the Main Menu.

a.m./p.m.

Definition: Use these abbreviations to refer to before and after noon.
Usage: Normal text rules.
Example: Select 12 hour to display time in a.m./p.m. formatted time.
Note: Do not use AM/PM, am/pm, or A.M./P.M.

antialias

Definition: Antialiasing is an effect that is applied to the edges of characters on a screen to make the characters look smoother. If characters on a screen are not antialiased the edges of the characters might appear jagged in some cases.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select the Best shapes option to antialias screen fonts where possible.
Note: Do not hyphenate this term, do not use anti-alias.

application

Definition: A class of program that is designed to perform a specific function. For example, a calculator or web browser. An application typically has an interface that is specific to the application.
Usage: Normal text rules. Use title capitalization for application names.
Tags:

Prose tag rules except when you refer to the Applications menu.

Use the application tag for application names.

Example: The Applications menu contains several applications, including the Calculator and gedit applications.
Note 1: If the application name does not follow standard capitalization rules, follow the capitalization of the application name. For example, use lowercase letters for the gedit application. When the application name begins with a lowercase letter, do not start a sentence with the name of the application.
Note 2: See also command and program.

archive, noun

Definition: A file containing one or more files in compressed format for more efficient storage and transfer.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: An archive can contain many files, folders, and subfolders, usually in compressed form.
Note 1: The verb that corresponds to the noun archive is compress.
Note 2: Do not use zip as a synonym for archive.

arrange

Definition: To organize items in an array or stack, using a specific characteristic to define the spatial relationship between the items. Essentially, arrange implies a two-dimensional or three-dimensional ordering of items. Typically, arrange applies to items in GUI-type applications, such as desktop icons, or folder icons.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can arrange the folder icons in your window by several characteristics, such as date of creation, status, name, and so on.
Note 1: Do not use sort as a synonym for arrange.
Note 2: See also sort.

ask

Definition: Use this verb for a request from the system to the user when there are two or more courses of action, and the system needs to know which course of action the user wants to take.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The system asks you if you want to continue with logging out.
Note 1: Do not use prompt as a synonym for ask.
Note 2: See also prompt.

Back Space

Definition: The Back Space key on the keyboard.
Usage: Title capitalization.
Tags: Use the keycap tag.
Example: To disable a shortcut, select the shortcut, click in the Shortcut column for the function you want to change, then press Back Space.
Note: The Back Space key might have a left arrow on the key.

backup, noun, adjective

Definition: A copy of a resource made as a precaution in case of loss of the original resource.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Select this option to display backup files in the view pane.
Note 1: Do not use backup as a verb.
Note 2: See also back up.

back up, verb

Definition: To copy files to another location as a precaution in case of loss of the original files.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Back up your files regularly.
Note 1: Do not use back up as a noun or adjective.
Note 2: See also backup.

bar

Definition: A part of a window that is peripheral to the main working part of a window, and that contains functionalities and utilities to use in performing work in the main working part of the window. A bar appears as a solid object on the same visual plane as the window. The contents of a bar form a unified whole.
Usage: Normal text rules.
Tags: Prose tag rules.
Example 1: To show text only in your toolbars, choose Text Only from the Button Labels drop-down list.
Example 2: To show the location bar in the file manager, choose View ▸ Location Bar.
Note: See also folderbar, location bar, menubar, pane, scrollbar, statusbar, toolbar.

blank

Definition: When no information is present in a field, refer to the field as blank.
Usage: Normal text rules.
Example: Enter the command that you want to run in the blank field on the Run Application dialog.
Note: Do not use empty when you refer to a field.

blind-copy

Definition: To copy a message to an address, so that that address does not appear in the delivered message.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Enter any email addresses to which you want to blind-copy the message.
Note 1: Hyphenate this term, do not use blind copy.
Note 2: The abbreviation bcc means blind carbon copy.

bounce keys

Definition: A keyboard accessibility feature. Use the bounce keys feature to ignore subsequent presses of the same key if they happen within the time that the user specifies.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The bounce keys control the key repeat characteristics of the keyboard.

Caps Lock

Definition: The Caps Lock key on the keyboard.
Usage: Title capitalization.
Tags: Use the keycap tag.
Example: To type in uppercase, press Caps Lock.

command

Definition: An order from a user to the operating system to perform a service such as start an application or list the files in a directory. A command can have options, parameters, and arguments.
Usage: Normal text rules.
Tags: Prose tag rules. Use the command tag for a command or a command specification.
Example: Use the gedit command to start the gedit application.
Note: See also application and program.

compress, verb

Definition:
  1. To transform data to minimize the space required for storage or transmission.
  2. A command used to perform this transformation.
Usage: Normal text rules.
Tags: Prose tag rules. Use the command tag for the name of the command.
Example: A compressed non-archive file is a file that is created when you use bzip, bzip2, gzip, lzop, or compress to compress a non-archive file. For example, file.txt.gz is created when you use gzip to compress file.txt.
Note 1: The noun that corresponds to the verb compress is archive.
Note 2: Do not use zip as a verb.

Ctrl

Definition: Use Ctrl to refer to the Control key on the keyboard.
Usage: Title capitalization.
Tags: Use the keycap tag.
Example: To save the document, press Ctrl+S.

cursor

Definition: A cursor is a symbol that indicates the position at which you can enter or delete text. The cursor is usually a blinking vertical bar.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Press Home to position the cursor at the start of the line.
Note: Do not use pointer as a synonym for cursor.

depressed

Do not use this term. Use the term pressed in.

directory

Definition: A special type of file that enables you to organize other files into a hierarchical structure. Only use the term directory when you make specific references to the structure of the file system.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The New Folder menu item creates a new folder on your desktop. This folder is located in the directory /.nautilus/desktop.

down arrow

Definition: The down arrow key on the keyboard.
Usage: All lowercase letters.
Tags: Use the keycap tag.
Example: To switch to the workspace below the current workspace, press Ctrl+Alt+down arrow.

email

Definition: Electronic mail message, or an electronic mail messaging application.
Usage: Normal text rules. You can use this term as a verb, a noun, or as an adjective.
Tags: Prose tag rules for the term email. Use the email tag for email addresses.
Example: The Inbox Monitor applet monitors your email.
Note: Do not use e-mail, E-mail, Email or any other synonym.

emoticon

Definition: A short sequence of characters, or an icon, that represents a facial expression. For example, the :-) emoticon represents a smiling face. In electronic communications, emoticons portray feelings that supplement messages. Evolution includes icons that represents emoticons.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To insert an emoticon to your message, choose Insert ▸ Smiley, then choose the emoticon that you require.

empty

Definition: When no information is present in a text box, refer to the text box as empty.
Usage: Normal text rules.
Example: Use the empty Name text box to specify a name for the application.
Note: Do not use blank when referring to a text box.

Enter

Definition: The Enter key on the numeric keypad.
Usage: Title capitalization.
Tags: Use the keycap tag for Enter.
Example: Press Enter on the numeric keypad to complete the calculation.
Note:

In Calculator the Enter key provides the same function as the equals sign (=).

Sometimes the Return key and Enter key perform the same functions. Refer to the Return key by default, and only refer to the Enter key when the user must press Enter, or when the user is likely to use the numeric keypad.

Esc

Definition: Use as an abbreviation for the Escape key on the keyboard.
Usage: Title capitalization.
Tags: Use the keycap tag.
Example: To cancel the dialog, click on the Cancel button or press Esc.

file system

Definition: A hierarchically structured network of files and directories that you can access.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The file system defines how files are named.
Note: Spell as two words, do not use filesystem.

folder

Definition: A representation of a directory in a graphical application. Use the term folder when you document applications that use folder icons to represent directories.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To create a folder, choose File ▸ New Folder.

FTP site

Definition: A location on the Internet from which you can download files using the File Transfer Protocol (FTP).
Usage: All uppercase letters for the term FTP, all lowercase letters in the term site.
Tags: Prose tag rules.
Example: You can use Nautilus to browse websites and FTP sites.

full screen

Definition: A mode that resizes the item that is displayed on the screen, so that the item is the same size as the screen.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To display the image in full-screen mode, choose View ▸ Full Screen.
Note: See also screen.

Help

Definition:

An online manual or other item of documentation that a user can access to find out more about how to use the GNOME Desktop. A user can access Help in any of the following ways:

  • In an application, choose Help > Contents.
  • For panels and panel objects, right-click on the object, then choose Help from the popup menu.
  • Start the Help browser application, then navigate to the required Help.
Usage: Title capitalization.
Tags: Prose tag rules.
Example: To view Help on the Calculator application, start Calculator, then choose Contents ▸ Help.
Note: In general, you do not need to use the term online Help, as Help is by definition online. However, if there is a possible ambiguity between the Help and another type of documentation, then you can use the adjective online to qualify Help.

hot key

Definition: A key or combination of keys that starts an application when pressed.
Usage: Normal text rules.
Tags:

Use the keycap tag for key names.

Use the keycombo tag for key combinations.

Example: To create a hot key, use the Keyboard Shortcuts preference tool.
Note: Do not use any other term for hot key.

icon

Definition: A class of image that represents a functional component of a computer system. In the GNOME Desktop, icons represent menus, menu items, launchers, and other user interface components.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To open a menu from a panel, click on the icon that represents the menu.
Note: See also image.

image

Definition: A visual representation that is electronically rendered. An image might or might not represent a real-world object. Pictures and icons are classes of image.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Choose an image for the panel background.
Note: See also icon.

inode

Definition: A data structure that contains information about individual files in UNIX file systems. Each file has one inode. An inode contains the node, type, owner, and location of a file.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Choose the Date Changed option to display the date that the inode of the item was last modified.
Note: Spell without a hyphen, do not use i-node.

Internet

Definition: The global association of networks and computers that share information.
Usage: Use an initial uppercase letter to refer to the Internet.
Example: Select this option to display Internet time in the applet.

key binding

Do not use this term. Use the term keyboard shortcut.

keyboard shortcuts

Definition:

A key or combination of keys that provides an alternative to the standard ways of performing an action. The GNOME Desktop provides the following types of keyboard shortcuts:

  • Access keys, to use the keyboard rather than the mouse.
  • Hot keys, to use the keyboard rather than the command line.
  • Shortcut keys, to use the keyboard rather than the user interface.
Usage: Normal text rules. See also the usage instructions for specific categories of keyboard shortcut.
Tags:

Use the keycap tag for key names.

Use the keycombo tag for key combinations.

Example: In a table that lists various types of key combinations, the column header for the key combinations should be Keyboard Shortcuts.
Note: Do not use key binding as a synonym for keyboard shortcut.

keypress

Definition: The action of pressing a key. This term refers to the first part of a keystroke action, that is, pressing the key. The term keypress does not refer to the second part of a keystroke action, that is, releasing the key.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Only accept a keypress after 30 milliseconds.
Note: Do not use keystroke as a synonym for keypress.

keystroke

Definition: The action of pressing and releasing a key.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Shortcut keys enable you to perform an action with one or more keystrokes or mouse clicks.
Note: Do not use keypress as a synonym for keystroke.

left arrow

Definition: The left arrow key on the keyboard.
Usage: All lowercase letters.
Tags: Use the keycap tag.
Example: To switch to the workspace to the left of the current workspace, press Ctrl+Alt+left arrow.

left mouse button

Definition: The mouse button on the left side of a mouse configured for right-hand use.
Usage: Normal text rules.
Example: In general, you use the left mouse button to control the applet functions.
Note: Do not use mouse button 1 or any other term.

left side

Definition: Use this term to refer to the left side of an item.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The side pane is on the left side of the Nautilus window.
Note: Do not use left-hand side.

login, noun, adjective

Definition: The process of gaining access to a session.
Usage: Normal text rules.
Tags: Prose tag rules.
Example of Noun: Select this option to display a splash screen on login.
Example of Adjective: The Options menu lists your login options.
Note: See also log in.

logout, noun, adjective

Definition: The process of terminating a session.
Usage: Normal text rules.
Tags: Prose tag rules.
Example of Noun: Select this option to display a confirmation dialog on logout.
Example of Adjective: Use the Sessions preference tool to specify logout behavior.
Note: See also log out.

look-and-feel

Definition:

A general term for the following features of a graphical user interface:

  • The visual characteristics of the components of the interface.
  • The characteristics of the interaction between the user and the interface.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Nautilus includes background patterns and colors that you can use to change the look-and-feel of the desktop background.
Note: This term is a single noun, do not use look and feel.

man page

Definition: A page of online documentation in UNIX systems.
Usage: Normal text rules.
Example: See the regex man page for further information on how to construct a regular expression.
Note: Spell as two words, do not use manpage.

Meta

Definition: The meta key on your keyboard. You can use the meta key as a modifier key.
Usage: Title capitalization.
Tags: Use the keycap tag with the term Meta when you use the term in a shortcut.

meta key

Definition: A key that you can use as a modifier key.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The default modifier key is the meta key.

middle mouse button

Definition: The mouse button between the left mouse button and the right mouse button.
Usage: Normal text rules.
Example: When you release the middle mouse button, floating panels remain in their current position.
Note: Do not use mouse button 2 or any other term.

MIME

Definition: Multipurpose Internet Mail Extension.
Usage: All uppercase letters.
Tags: Prose tag rules.
Example: The MIME type of a file enables applications to read the file.

MIME type

Definition: A MIME type identifies the format of a file, and enables applications to read the file. For example, an email application can use the image/png MIME type to detect that a PNG file is attached to an email.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Choose the MIME type option to display the MIME type of the file.

mnemonic

Do not use this term. Use the term access keys.

Modifier

Definition: The key on your keyboard that you have defined as the Sawfish modifier key.
Usage: Title capitalization.
Tags: Use the keycap tag with the term Modifier when you use the term in a shortcut.
Note: You can define a modifier key for the Sawfish window manager in the Sawfish preference tool.

modifier key

Definition: A key that only performs an action when combined with another key.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Alt, Ctrl, and Shift are modifier keys.

mouse keys

Definition: A keyboard accessibility feature. Use the mouse keys features to configure the numeric keypad on your keyboard to emulate mouse actions.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can specify three mouse keys settings.

onscreen, adjective

Definition: As shown on a display screen.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The desktop contains an onscreen keyboard application to enable users with a physical disability to use the desktop.
Note: Do not hyphenate this term, do not use on-screen.

pane

Definition:

A subdivision of the main working part of a window, where the user works and interacts with the application. A pane provides the impression that you are viewing items that are in a visual plane beneath, or behind, the visual plane of the window.

A pane contains discrete objects, that is, the contents of a pane do not form a unified whole. Typically, a pane displays the work that a user is doing, or routes to that work. A pane is usually surrounded by a frame.
Usage: Normal text rules.
Tags: Prose tag rules.
Example 1: To show the preview pane in Evolution, choose View ▸ Preview Pane.
Example 2: To show the side pane in the file manager, choose View ▸ Side Pane.
Note: See also bar.

permission

Definition: A setting assigned to each file and directory to determine which users have access to read, write, and execute the contents of that file or directory.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can edit the contents of the system menus if you have write permission for the files and folders that correspond to the system menus.

plugin

Definition: A supplementary application that you can add to an application to enhance the functionality of the application.
Usage: Normal text rules.
Tags: Use the application tag for the names of plugins.
Example: To install a plugin in gedit, choose Plugins ▸ Manager.
Note: Do not use plug-in.

pointer

Definition: A small arrow or other symbol on your screen that you move with a mouse or other pointing device.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The pointer can provide feedback about a particular operation, location, or state.
Note 1: Do not use the term cursor as a synonym for pointer.
Note 2: If there is any ambiguity about what the term pointer refers to, use the term mouse pointer.

preference

Definition:

A characteristic of an application that determines how the application behaves in relation to the user. Users can choose a preference from a range of alternatives to specify how they want to work with the application. For example, a user can specify whether or not to display a statusbar in gedit.

Applications and applets have associated preferences. Examples of preferences include the following:

  • Whether all GNOME-compliant applications on the GNOME Desktop display a toolbar.
  • Whether the Workspace Switcher applet displays workspaces as images or as names.
  • Whether the Window List applet displays the windows from the current workspace or from all workspaces.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To set the preferences for an applet, right-click on the applet, then choose Preferences.
Note: See also property.

pressed in

Definition: Use this term to describe the indented appearance of a button.
Usage: Normal text rules.
Example: The window button remains pressed in until the screenshot capture is complete.
Note:

Do not use depressed to describe an indented button.

Do not use depress as a verb to describe pressing a key or mouse button.

Print Screen

Definition: The Print Screen key on the keyboard.
Usage: Title capitalization.
Tags: Use the keycap tag.
Example: To take a screenshot of the GNOME Desktop, press Print Screen.

privileges

Definition: A set of special permissions granted to a user to perform various operations on a system.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The system administrator is a special user who has privileges to perform all administrative tasks on a system.

program

Avoid using this term in end-user documentation. See application and command.

prompt, verb

Definition: Use this verb for a request from the system to the user to perform a specific action to continue.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The system prompts you for your username.
Note 1: Do not use ask as a synonym for prompt.
Note 2: See also ask.

property

Definition:

A characteristic of an object. Each instance of an object can have different property settings. Files, folders, panels, and panel objects have properties. Examples of properties include the following:

  • The size of a file or folder.
  • The name of a file or folder.
  • The icon that represents a file or folder.
  • Whether a panel is set to autohide.
  • The command for a launcher.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To set properties for the folder, right-click on the folder then choose Properties from the popup menu.
Note: See also preference.

repeat keys

Definition: A keyboard accessibility feature. Use the repeat keys feature to specify the autorepeat settings for your keyboard.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use the repeat keys feature to enable keyboard autorepeat.

reply-to address

Definition: An address to which all responses to a message are addressed automatically. Your reply-to address can be the same as your normal email address.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To display your reply-to address in the Compose a message window, choose View ▸ Reply-To Field.
Note: Spell with a hyphen, do not use reply to address.

Return

Definition: The carriage return key on the alphanumeric part of the keyboard. In a text editor this key moves the cursor to the start of the next line. You can also use the Return key to initiate an action on the dialog element that has focus.
Usage: Title capitalization.
Tags: Use the keycap tag for Return.
Example: To pipe the output of an ls command to a text file, type the following command and press Return: ls | gedit
Note: Sometimes the Return key and Enter key perform the same functions. Refer to the Return key by default, and only refer to the Enter key when the user must press Enter, or when the user is likely to use the numeric keypad.

right arrow

Definition: The right arrow key on the keyboard.
Usage: All lowercase letters.
Tags: Use the keycap tag.
Example: To switch to the workspace to the right of the current workspace, press Ctrl+Alt+right arrow.

right mouse button

Definition: The mouse button on the right side of a mouse configured for right-hand use.
Usage: Normal text rules.
Example: Use the right mouse button to modify the applet.
Note: Do not use mouse button 3 or any other term.

right side

Definition: Use this term to refer to the right side of an item.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Edit the details for the bookmark on the right side of the Edit Bookmarks dialog.
Note: Do not use right-hand side.

root

Do not use this term without an associated noun. See root directory, root file system, root folder, root password, root privileges, and root user.

root directory

Definition: The top-level directory of the root file system. The root directory includes all other directories. The root directory has no name, and is represented on UNIX systems by the following special character: /
Usage: Normal text rules.
Tags:

Prose tag rules.

Use the filename tag for a directory that is actually named root, for example, /root.
Example: Click Save to save the file in the root directory.
Note: See also root file system.

root file system

Definition: The main file system on your computer. The root file system is organized as a hierarchy or tree.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: When a file system is mounted, the contents of the file system are accessible from the associated mount point inside the root file system.
Note: See also root directory.

root folder

Definition: The top-level folder in an archive manager application or file manager application.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Click Create to add the selected files to the root folder of the specified archive.
Note: See also archive.

root password

Definition: The password for the root user.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Type the root password, then click OK.
Note: See also root user.

root privileges

Definition: A set of permissions that enables you to perform system administration tasks that can normally only be performed by the root user.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You must have root privileges to configure the login screen.
Note: See also root user.

root user

Definition: The system administrator. The root user has the ability to create or delete user accounts, install software or hardware and perform other system administrator tasks. The username of the root user is root.
Usage: Normal text rules.
Tags:

Prose tag rules.

Use the literal tag for the username root.

Example 1: Log in as the root user to change user passwords.
Example 2: Typically, system administrators log in with the root username.
Note: See also root directory, root password, root privileges.

runlevel

Definition: A software configuration under which a selected group of processes exists.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: This field contains the command that the system runs to switch to runlevel 2.
Note: Do not use the two-word form run level, or the hyphenated form run-level.

screen

Definition: The area on a computer monitor, or any other computer device, where text and graphical information is displayed.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use the slider to specify the speed at which your mouse pointer moves on your screen when you move your mouse.
Note: See also full screen.

screensaver

Definition: A screensaver is an application that replaces the image on a screen when the screen is not in use. The screensaver application for the GNOME Desktop is XScreenSaver.
Usage: Normal text rules.
Tags: Prose tag rules.
Example 1: When you lock your screen, the screensaver starts.
Example 2: Use the Mode drop-down list to specify the behavior of the screensaver application.
Note 1: If screensaver might be confusing in a particular context, use the more specific term screensaver application.
Note 2: Do not use screensaver display as a synonym for screensaver.

screensaver display

Definition: A screensaver display is the animation that is displayed on your screen when the screen is not in use. You can use your screensaver application to choose a screensaver display to show on your screen when the screensaver application starts.
Usage: Normal text rules.
Tags: Prose tag rules.
Example 1: Some screensavers can capture a frame of video, then manipulate the captured image to create your screensaver display.
Example 2: Use the Cycle After spin box to specify how long to show a screensaver display before changing to another screensaver display.
Note: Do not use screensaver as a synonym for screensaver display.

screenshot

Definition: A file that is an image of an area of the GNOME Desktop, or an image of the entire GNOME Desktop.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use this slider to specify the delay when you take a screenshot of the entire GNOME Desktop.
Note: Do not use screen shot, screen-shot, screen capture, screen grab, or any other term.

Shift

Definition: The Shift key on the keyboard.
Usage: Title capitalization.
Tags: Use the keycap tag.
Example: Press-and-hold Shift, then drag the item to the location where you want the link to reside.

shortcut

Definition: An action or a sequence of actions that is performed by a combination of one or more keystrokes or mouse clicks. A shortcut provides a quicker and more convenient way to perform an action than the conventional way to perform the same action.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can use the Shortcuts dialog pane to view, add, edit, or delete shortcuts from keymaps.
Note 1: Do not use the following terms as synonyms for shortcut:
  • Keyboard accelerator
  • Keyboard shortcut
Note 2: Only use this term in relation to the Sawfish window manager and preference tool.

shortcut command

Definition: Use to refer to a faster way to run a command.
Usage: Normal text rules.
Example: The macro facility provides up to 99 shortcut commands.
Note: Do not use short-cut.

shortcut keys

Definition: A combination of keys that enables you to jump straight to the action you want to perform, rather than using the user interface to open menus and choose the required command.
Usage: Normal text rules.
Tags:

Use the keycap tag for key names.

Use the keycombo tag for key combinations.

Example: To open a new file, use the Ctrl+N shortcut keys.
Note: Do not use the term accelerator key for shortcut key.

slow keys

Definition: A keyboard accessibility feature. Use the slow keys feature to control the period of time that you must press-and-hold a key before acceptance.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can specify four slow keys settings.

sort

Definition: To organize items in a list, using a specific characteristic to prioritize the ordering of items in the list. Essentially, sort implies a one-dimensional ordering of items.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can sort items in the list by several characteristics, such as date of creation, status, name, and so on.
Note 1: Do not use arrange as a synonym for sort.
Note 2: See also arrange.

spacebar

Definition: The spacebar key on the keyboard.
Usage: All lowercase letters.
Tags: Use the keycap tag.
Example: To open the Window Menu, press Alt+spacebar.
Note: Do not use space or space bar.

spam

Definition: Unsolicited email messages that you receive. Spam messages are usually intended to promote a product or service. Most email applications enable you to use filters to deal with your spam.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Use filters to deal with spam.

spellchecker

Definition: A tool that you can use to check the spelling of a document.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To start the spellchecker, choose Edit ▸ Spell Check Document.
Note: Do not use spellcheck as a verb, use check spelling instead.

sticky keys

Definition: A keyboard accessibility feature. Use the sticky keys feature to perform multiple simultaneous keypress operations by pressing the keys in sequence.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can specify two sticky keys settings.

strikeout

Do not use this term. Use the term strikethrough.

strikethrough

Definition: A text formatting characteristic where the text appears with a horizontal line through the text.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: To apply strikethrough formatting to text, select the text, then choose Format ▸ Style ▸ Strikethrough.
Note: Do not use the term strikeout as a synonym for strikethrough.

superuser

Do not use this term. Use root user instead.

symbolic link

Definition: A special type of file that points to another file or folder. When you perform an action on a symbolic link, the action is performed on the file or folder to which the symbolic link points.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: When you delete a symbolic link, you delete the link file, not the file to which the symbolic link points.
Note: You can shorten symbolic link to link when you are clearly referring to a symbolic link.

system administrator

Definition: A user with root privileges on a UNIX system.
Usage: Normal text rules.
Example: Your system administrator might set your default Menu Panel according to your local requirements.
Note: Avoid using superuser and root.

Tab

Definition: The Tab key on the keyboard.
Usage: Title capitalization.
Tags: Use the keycap tag.
Example: To switch between windows, use the Alt+Tab shortcut keys.

thread

Definition: A set of email messages, composed of an initial message about a subject and all responses to that message.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: When you display your messages by thread, you can view the messages on a particular subject in chronological order.

tile

Definition: To cover an area with objects that do not overlap.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: You can use the Background preference tool to tile the desktop with an image.

toggle key

Definition: A key that can switch between two states.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The Num Lock, Caps Lock, and Scroll Lock keys are toggle keys.

unavailable

Definition: When you cannot interact with a GNOME Desktop interface item, describe the item as unavailable.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: The toggle menu items are unavailable when you view a document that contains only one page.
Note: Do not use inactive, dimmed, or grayed out.

UNIX

Definition: A multi-user, multitasking operating system. UNIX is a registered trademark of The Open Group. The Open Group spell UNIX in all uppercase.
Usage: All uppercase letters.
Tags: Prose tag rules.
Example: Developers are the primary users of UNIX time.
Note: Do not use Unix, or any other term, unless you have to directly quote the interface.

up arrow

Definition: The up arrow key on the keyboard.
Usage: All lowercase letters.
Tags: Use the keycap tag.
Example: To switch to the workspace above the current workspace, press Ctrl+Alt+up arrow.

websafe color palette

Definition: The websafe color palette is a general-purpose palette of 216 colors. The websafe color palette is designed to optimize the use of color on systems that support 8-bit color.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: Applications that do not use the websafe color palette have less colors available.
Note: The websafe color palette is also called the Netscape color palette and the Netscape color cube. In GNOME documentation, use the term websafe color palette only.

website

Definition: A location on the World Wide Web.
Usage: Normal text rules.
Example: You can find the GNOME Documentation Style Guide on the GNOME Documentation Project website.
Note: Spell as one word, do not use web-site, or web site.

World Wide Web

Definition: A system of Internet servers that support HTML documents. You can click on links in HTML documents to view other documents on the World Wide Web.
Usage: Title capitalization.
Tags: Prose tag rules.
Example: You can use Mozilla to browse the World Wide Web.
Note: You can shorten World Wide Web to Web when you are clearly referring to the World Wide Web.

zip, noun

Definition: An archive format created by an application such as PKZIP or WinZip.
Usage: Normal text rules.
Tags: Prose tag rules.
Example: File Roller supports zip files, as well as several other archive formats.
Note 1: Do not use zip as a verb. Use the verb compress instead.
Note 2: Do not use zip as a synonym for archive.

B. Units

This appendix lists the decimal multipliers and unit abbreviations to use in GNOME documentation.

B.1. Multipliers

To avoid awkward strings of zeroes, large numbers are usually written in a shorthand power-of-ten format. A multiplier is added to the unit as a prefix to indicate the appropriate order of magnitude. You can use the following types of multipliers:

Decimal multipliers

Indicate the order of magnitude of a number in the decimal system.

Binary multipliers

Indicate the order of magnitude of a number in the binary system.

The following table lists decimal multipliers.

Table B-1 Decimal Multipliers
Multiplier Abbreviation Order of Magnitude
peta P 1015
tera T 1012
giga G 109
mega M 106
kilo k 103
deci d 10-1
centi c 10-2
milli m 10-3
micro u 10-6
nano n 10-9

The following table lists binary multipliers.

Table B-2 Binary Multipliers
Multiplier Abbreviation Order of Magnitude
Kilo K 210 = 1024
Mega M 220 = 1,048,576

B.2. Unit Abbreviations

This section provides guidelines about the correct unit abbreviations to use in GNOME documentation.

  • The form for abbreviations is the same for both singular and plural.
  • Be aware of the distinction between uppercase and lowercase letters, especially for the prefixes.
  • Avoid using units in titles and headings.
  • Spell out the full name of the unit for clarity where necessary.

The recommended units in the following table are based on the Systeme International d'Unites (SI) system of units. The table is not an exhaustive list of all SI units. The table only includes those units that occur in the desktop, or in GNOME documentation. If you need to use units that are not defined in the table, send your suggestions to: Pat Costello

Table B-3 Recommended Units for GNOME Documentation
Term Unit Example Abbreviated Example
bit b 48 Kilobit 48 Kb
byte B 10 Megabytes 10 MB
decibel dB 100 decibels 100 dB
degree Celsius oC Zero degrees Celsius 0 oC
degree Fahrenheit oF 32 degrees Fahrenheit 32 oF
hour h 24 hours 24 h
inch in 12 inches 12 in
meter m 1 kilometer = 1000 meters 1 km = 1000 m
minute of time min 10 minutes 10 min
second of time s 30 milliseconds 30 ms

C. Glossary of Terms in This Guide

This glossary contains a list of terms in the GNOME Documentation Style Guide, for which contributors to the GNOME Documentation Project have requested clarification. If you find terms that are unfamiliar to you in this guide, ask Pat Costello to include a definition in the following list.

gerund

The "-ing" form of a verb. You can use the gerund as part of a verb form, or as a noun.

Example: The system is running at full power.

The gerund running is part of the present continuous verb is running. An ambiguity arises when you use a gerund as a noun.

Example: The running system requires power.

Saxon genitive

A language construction that denotes possession, derived from Old Saxon. The construction is present in all languages that have a distinct Germanic influence, including English. The genitive form is not present in Latin-derived languages, or non-European languages, and can therefore cause difficulty for readers and translators. The genitive form is created by adding apostrophe s to the end of a proper noun. In the original form, the genitive was created by adding an -es suffix to a noun. The apostrophe in the English form of the genitive denotes the missing letter e.

Example: The man's car = the car belonging to the man.

D. Examples of Information Design Building Blocks

This appendix provides examples of some of the information design building blocks discussed in Chapter 2 ― Basic Building Blocks of Information Design. If there are other information design blocks that you think need further explanation, send your suggestions to Pat Costello . You can use the following jump list to navigate quickly to the section you want to read.

D.1. Level-One Headings

The heading at the start of this section is a level-one heading.

D.1.1. Level-Two Headings

The heading at the start of this section is a level-two heading.

D.1.2. Another Level-Two Heading

The heading at the start of this section is also a level-two heading.

D.1.2.1. Level-Three Headings

The heading at the start of this section is a level-three heading.

D.1.2.2. Another Level-Three Heading

The heading at the start of this section is also a level-three heading.

D.1.2.2.1. Level-Four Headings

The heading at the start of this section is a level-four heading.

D.1.2.2.2. Another Level-Four Heading

The heading at the start of this section is also a level-four heading.

D.2. Tables

The following table is an informal table.

Informal tables No table number, no caption, do not appear in the table of contents.
Formal tables Table number, caption, usually appear in the table of contents.

Table D-1 is a formal table.

Table D-1 Table Types
Table Type Characteristics
Informal No table number, no caption, do not appear in the table of contents.
Formal Table number, caption, usually appear in the table of contents.

E. GDSG Contributors

This appendix lists the contributors to the various sections of the GNOME Documentation Style Guide.

Section Contributors
Publishing Editor and Coordinator Pat Costello
Preface

Pat Costello

Also:

John Fleck

Chapter 1 ― Fundamental Concepts of Technical Documentation

Pat Costello

Also:

John Fleck

Chapter 2 ― Basic Building Blocks of Information Design Irene Ryan
Chapter 3 ― Grammar and Usage Guidelines Pat Costello
Chapter 4 ― Writing Documentation for an International Audience Pat Costello
Chapter 5 ― Ways to Improve Your Documentation Pat Costello
Chapter 6 ― Indexing Your Documentation Pat Costello
Chapter 7 ― Writing for GUIs Eugene O'Connor
Chapter 8 ― Usability and Readability Considerations for Technical Documentation Pat Costello
Chapter 9 ― Writing Accessible Documentation Pat Costello
Chapter 10 ― Use of Screenshots Eugene O'Connor
Chapter 11 ― Legal Topics Pat Costello
Appendix A ― Recommended Terminology

Coordinator: Eugene O'Connor

Also:

Pat Costello

John Fleck

Sasha Kirillov

Breda McColgan

Michael McElree

Irene Ryan

Gordon Sidaway

Appendix B ― Units

Pat Costello

Also:

Gordon Sidaway

Appendix C ― Glossary of Terms in This Guide Pat Costello
Appendix D ― Examples of Information Design Building Blocks Pat Costello
Appendix E ― GDSG Contributors Pat Costello

  • GNOME-STYLE