You build your communications out of visual elements: the ink marks of your words, sentences, and paragraphs against the background of the page, as well as your drawings and graphs and tables. Your readers see the visual design of these elements before they read and understand your message. And what they see has a powerful effect on the success of your communications, on its usability and persuasiveness. Effective design results in users being able to locate, understand, and use information easily.

Good design enhances usability; it helps readers:

• locate information quickly
• notice highly important content
• understand information so that they can use it

Good design affects readers’ attitudes, thereby increasing a communication’s effectiveness; it helps readers:

• feel that they can successfully engage with the content, and therefore read and keep reading
• feel a sense of accomplishment about understanding the content.

Because document design can have such a significant impact on your communication’s usability and effectiveness, you should approach design in the same reader-centered manner that you use when drafting text and graphics. Think continuously about your readers: who they are, what they want from your communication, the context in which they will be reading.

The following video clearly discusses and illustrates the importance of design in technical writing, including its physical, cognitive, and affective aspects as well as basic principles of design (contrast, alignment, proximity, white space, and repetition).

Elements of Design

Consider the following elements of design when you create a technical document of any sort – description, instructions, report, web page. Although each specific type of technical document will have its own conventions and ways in which design elements are applied, it’s helpful to be mindful of these building blocks of design, as professional graphic designers are.

• Text. Paragraphs and sentences—avoid big blocks of dense text. Maintain clear and clean margins.
• Headings and titles. Label sections of your communication for user ease of finding information and understanding how information is organized in the document, and therefore what to expect.
• Graphics. Include titles or labels for all tables and figures. Place all graphics as near as possible to the accompanying text that refers to and explains the graphics.
• White space. Maintain enough blank space in a document to avoid big blocks of text and a clutter from too many visuals or background images.
• Repetition. Maintain the same format for similar items throughout, e.g., repeat heading formats, place similar information similarly in the layout, etc.
• Contrast. Ensure that all items are easy to read. High contrast, such as black type on a white background, is easiest to discern.
• Alignment. Put all headings and subheadings at the left-hand margin. It’s generally easier to read single-spaced text that is left-justified (no indentations), with spaces between paragraphs. Keeping everything left-justified accomplishes two things: it makes the headings easier to find, and it shortens the main text’s line length.

Additional Elements: Color, Font, Highlighting

Color

• Use colors to support your message; select colors with appropriate associations.
• Use color for emphasis, not decoration.
• Provide high contrast between text and background.
• Limit the number of colors.
• Choose a color scheme, not just individual colors, so that color unifies the communication.

Font

• Limit the number of fonts to no more than two-three. If you use different fonts, apply them consistently throughout the document, e.g., one for headings and one for main text.  It’s also fine to use one font throughout.
• Choose an easy-to-read sans serif font (Calibri, Arial).
• Italics draw attention to text because they make it harder to read. Use italic font sparingly to draw attention. Do not over-use italics.

Highlighting in Software Documentation

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

Here are some standard 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 highlighting schemes.
• 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.