# 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 GNOME Handbook of Writing Software Documentation. contains examples of some of the information design building blocks in this chapter.

## 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.

### 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

## 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.

### 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.

## 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.

### 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.

#### 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.

#### 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.

## 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.

### Guidelines for Using Graphics

Use the following guidelines to include graphics in your material:

- Use graphics to provide additional technical information that is not provided by the text. Do not repeat existing text information in graphic format.

- Where necessary, use a complete sentence to introduce a graphic. Use the introductory sentence to put the graphic into context.

- Consider the type of material you are writing, and how users access the material, before you include screenshots of the application. There are different considerations for online Help and printed manuals. See the following sections:

#### 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.

#### 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.

### 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.

### Guidelines for Using Screenshots in Printed Manuals

Some GNOME Desktop distributions have a requirement to print manuals covering broad topics, such as the GNOME 2.0 Desktop User Guide. 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.

## 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

### 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.

### 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

### 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.

### 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 ...

## Cross-References

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

### 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.

## 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.

## 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.

### 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.