7. Constructing Text





This chapter provides information about the use of text and graphics elements in your documents, such as section heads, tables, and cross-references. There are different ways to present these elements. The design, layout, and writing style that you choose will help to make your document unique.

The style and writing conventions in this chapter include suggestions that have worked successfully in published computer documents. You may decide to adopt these conventions, or to adapt them to your company's documentation. Whatever convention you choose, make sure that the format is easily recognized and understood by readers, and that you use your style consistently throughout a document.

Topics

Section Heads

Heads concisely describe the material in the section that follows. No matter what their level, heads are not titles. Heads summarize information; titles name information.

The appropriate placement of document heads is dependent upon the content and flow of information, and sometimes on the page layout. For example, several pages of material may fit well within the context of a single level-one head, while a sentence or two may require a level-four head.

Writing Heads

Section heads should group topics within a chapter and provide a point of reference for a reader. Heads are hierarchical; you must carefully build heads and text in a logical and understandable progression. Level-one heads provide the broadest division, followed by level-two heads, and so on.

When writing heads:

    For example, in a section introducing a new type of modem to an end user, write "Speedway II Modem Features" rather than "Introduction."

    You may need to reorganize your text if there are three or more level-one heads on a single page. Also, try to have at least two heads at each level you're using.

    If a head level includes gerunds (for example, "Opening," "Installing"), then try to write all other heads at the same level with gerunds.

      <Head2>Remote Digital Loopback

        Awkward: This tests the system's ability to . . . .

        Better: The remote digital loopback test examines . . . .

Capitalizing and Punctuating Heads

The design of your document should include how you capitalize and punctuate section heads. The design you choose for heads should complement the design of chapter titles, and figure and table captions in your document. Some documents follow traditional rules of title capitalization for section heads, while others develop a unique look.

Following traditional guidelines for heads, you would:

Following options for a unique design, you can:

    For instance, you could:

      USE ALL CAPS

      Use an italic font

      Use an Alternative Font

Numbering Heads

Unnumbered heads are generally used within documents that are geared for end users, while numbered heads are reserved for more technical reference and service manuals.

Numbered section heads use the chapter number as the first digit. This digit is separated from the next digit, which represents the level-one head. The third digit represents the level-two head, followed by the digit for the level-three head, and so forth. All digits are separated by a delimiter, such as a period or an endash.

The section number 4.2.3.1 tells readers that the text is in Chapter 4, the second level-one head, the third level-two head, and the first level-three head. Sections would be numbered in this way:

    4.2

      4.2.1

      4.2.2

      4.2.3

        4.2.3.1




(Continued...)