Upon completion of this chapter, readers will be able to: Explain and apply design guidelines for heading and list use in technical documents. Explain and apply design guidelines for including notices in technical documents. Explain and apply design guidelines for table and figure use in technical documents. Explain and apply design guidelines for text highlighting and alignment in technical documents. Explain and apply design guidelines for font and color in technical documents

McMurrey, David

English

DigitalCommons@Kennesaw State University

Kennesaw State University DigitalCommons@Kennesaw State University Open Technical Communication Open Educational Resources 7-1-2019 04.03: Page Design David McMurrey hcexres@io.com Follow this and additional works at: https://digitalcommons.kennesaw.edu/opentc  Part of the Technical and Professional Writing Commons Recommended Citation McMurrey, David, "04.03: Page Design" (2019). Open Technical Communication. 19. https://digitalcommons.kennesaw.edu/opentc/19 This Article is brought to you for free and open access by the Open Educational Resources at DigitalCommons@Kennesaw State University. It has been accepted for inclusion in Open Technical Communication by an authorized administrator of DigitalCommons@Kennesaw State University. For more information, please contact digitalcommons@kennesaw.edu. 1/8/2020 Page Designhttps://softchalkcloud.com/lesson/files/GZgMx1yw3kRhzL/4_3PageDesign_print.html 1/3Page Design David McMurrey and Jonathan ArnettChapter ObjectivesUpon completion of this chapter, readers will be able to:1. Explain and apply design guidelines for heading and list use in technical documents.2. Explain and apply design guidelines for including notices in technical documents.3. Explain and apply design guidelines for table and figure use in technical documents.4. Explain and apply design guidelines for text highlighting and alignment in technicaldocuments.5. Explain and apply design guidelines for font and color in technical documents.Common Page Design Page design means different things to different people, but here it will mean the use of typography and formatting suchas you see in professionally-designed documents.Our focus here is technical documentation, which implies modest, functional design.For even more detail than you see here, consult these two standard industry resources:Sun Technical Pubs. Read Me First! Any recent edition. Prentice Hall.Microsoft Corporation. Microsoft Manual of Style for Technical Publications. Any recent edition. Microsoft Press.HeadingsThe following presents some of the standard guidelines on headings.Insert plenty of headings, perhaps one heading for every two to three paragraphs. Avoid overkill, though: lots ofheadings with only one or two sentences per heading does not work.Indicate a heading's level through design. Use type size, type style, color, boldness, italicization, and alignment tomake a heading's level obvious. ("Levels" of headings are like levels in an outline: Level 1 corresponds to thelarge, capitalized roman numerals; Level 2 to the capital letters; Level 3 to the arabic numerals; Level 4 to thelower-case roman numerals; and so on.)Limit the levels of heading. Most documents only need three or fewer levels of heading; more levels can confuseyour readers.Describe the sections' contents with specific language. Vague headings like "Technical Background" don't tellanybody anything.Use parallel phrasing. Parallel headings tell readers if the sections are similar to each other.Avoid "lone headings." If you have one heading, you should use a second. It's the same concept as having an "A"without a "B" or a "1" without a "2" in outlines.Avoid "stacked headings" (two or more consecutive headings without text in between).Don't use a pronoun to refer to a heading. If you have a heading like "Configuring the Software," don't follow it witha sentence like "This next phase..."Consider the "hanging-head" format for major headings. In this design, some or all of the headings are on the leftmargin, while all text is indented one to two inches. This format will make headings stand out more and reduce themain text's line length.Consider using "run-in" headings for your lowest-level headings. In this design, the heading "runs into" thebeginning of a paragraph and ends with a period. You can use some combination of boldness, italics, or color forthese headings. This format avoids the problem of lower-level headings blending in with each other.Lists1/8/2020 Page Designhttps://softchalkcloud.com/lesson/files/GZgMx1yw3kRhzL/4_3PageDesign_print.html 2/3Lists are useful tools for emphasizing important points, enabling readers to scan text rapidly, and providing more whitespace. The following presents some of the standard guidelines on lists.Use numbered lists to show sequence, order, or hierarchy. Use bulleted lists for items that can appear inany order.Use standard numbered- and bulleted-list formats. They are built into word-processing programs, and HTML hasordered- and unordered-list tags.Use parallel phrasing for lists' contents.Introduce all lists with lead-in text; don't start a list immediately after a heading.Unless your organization's style overrides, punctuate list items with a period only if they are complete sentencesor have embedded dependent clauses.Be consistent with using initial caps or lower-case letters on the first words of list items. Use different symbols for the second levels of nested lists. For numbered lists, use lowercase letters. For bulletedlists, use bolded en dashes or empty-centered circles. In either case, make sure that nested items align to thetextof the previous level.Avoid using too many lists or overstuffing lists. Seven to ten items is generally about the maximum number ofitems.NoticesNotices are specially-formatted chunks of text that alert readers to special points, exceptions, potential problems, ordanger. The following presents some of the standard guidelines for notices.Make notices more prominent and noticeable as they become more severe. Consider using this standardhierarchy:"Danger" for situations that could involve severe injury or death"Warning" for situations that could involve minor injury"Caution" for situations that could involve equipment damage, data loss, or a threat to a procedure'ssuccess "Note" for exceptions or situations that do not require the preceding tagsWhatever notice design you use, avoid using long strings of bold text, italics, capital letters, or combinations ofthese. In addition to telling readers to do or not do something, explain three things:under what conditions they should use the noticewhat will happen if they ignore the noticehow to recover if they ignore the noticeMake notices' text succinct, but not at the expense of clear writing. Avoid telegraphic writing style (omitting articleslike a, an, the) in notices.In numbered lists, align notices to the text of the list items they apply to. Put notices in two places:before the step in which the potential problem existsat the beginning of the entire procedureFiguresFigures are illustrations, drawings, schematics, photos, and other visual materials. The following presents some of thestandard guidelines on figures.In the text before each figure appears, provide a cross-reference to the figure.If you include a label and caption, place them below each figure.Omit labels and captions if they have no vital function and are not needed (for example, in instructions when thefigures are closely related to the individual steps).TablesTables are like lists, which were discussed previously, but are more structured and formal. In your text, look for repeatingpairs, triplets, or quadruplets of items that can be formatted as tables. For example, a series of terms and definitions is aclassic use for tables. The following presents some of the standard guidelines for tables.Look for repeating groups of items in your text that you can format as tables.In the text before each table appears, provide a cross-reference to the table.Include a table title unless the content of the table is utterly obvious and the table contains few items. Place thetable title above the table, or make it the top row of the table.1/8/2020 Page Designhttps://softchalkcloud.com/lesson/files/GZgMx1yw3kRhzL/4_3PageDesign_print.html 3/3Use column and row headings (or both) to define the contents of the columns and rows. Consider highlightingthese headings.Left-align text columns (unless the contents are simple alphabetic characters). Left-align text columns with theirheadings.Right-align or decimal-align numerical data, and center it under its heading.Put standard measurement units (ft, mm, gal.) in the column or row heading rather than with each item in thecolumn or row.Briefly discuss the main trend in the table—what you want readers to notice.HighlightingSoftware documentation typically uses a lot of highlighting. Highlighting here refers to bold text, italics, alternate fonts,capital letters, quotation marks, and other typographical tricks used to call attention to text. The following presents somestandard guidelines for highlighting.Establish a plan for using highlighting, and apply it consistently.Use highlighting for specific, functional reasons. Avoid too much highlighting, and avoid complicated highlightingschemes.Consider using this fairly standard highlighting scheme:For simple emphasis, use italics.Use bold for commands, on-screen buttons and menu options.Use italics for variables for which users must supply their own words.Use an alternate font for text displayed on screen or text that users must type in.For screen and field names, use the capitalization style shown on the screen but no other highlighting.Use an initial cap for key names but no other highlighting.For extended emphasis, use the notice format.Margins, Indentation, & AlignmentAs mentioned in the section on headings, you may wish to indent main text one to two inches while leaving headings onthe left margins. This style does two things: it makes the headings stand out, and it shortens the main text's line length.Fonts & ColorHere are some suggestions concerning fonts and color:Limit the number of main fonts that appear in a document to two. For example, you might use Arial for headingsand Times New Roman for body text.Use only one alternate font, at most two. For example, you might use Arial for headings, Times New Roman forbody text, and Courier New for text that users will see onscreen or that users must type in.If you use color, use it minimally and consistently. For example, if you have black text on a white background, youmight select another color for headings. You might use that same color for figure and table titles as well as thetags for notices (the actual "Note," "Warning," "Caution," and "Danger" labels on notices).Avoid unusual combinations of background and text colors. For example, purple or red text on a black backgroundis unreadable. Stick with black text on a white or gray background unless there is a strong, functional reason forsome other color combination.

04.03: Page Design

https://digitalcommons.kennesaw.edu/cgi/viewcontent.cgi?article=1018&amp;context=opentc

04.03: Page Design

Abstract

Similar works

Full text

Available Versions

DigitalCommons@Kennesaw State University