Sections of this topic
Technical Writers do more than just write. They communicate relevant technical information to get jobs done; see previous posts on what a Technical Writer does (see Defining a Technical Writer). They create the documentation, but how do they present an effective and appealing document? In a previous post, we discussed how to create a Style Guide and the importance of them. The guide allows the writer to focus on writing the content, and less on the look and feel of the document. No matter which Style Guide is followed, there are certain popular generic rules that should be followed. You might say the items mentioned below, can be part of a Style Guide.
To increase the visual appeal of a document, we should adhere to certain rules the same way we do for grammar. If the document is too long, does not present any illustrations, and is strictly text, the user will have a problem just reading the first page. Readers will usually flip through the document to see how it is structured. If it has a lot of white space, images, and has varying styles and formats, then viewers will more likely read it. Apply some of the following tips:
- Insert images; use plenty of graphics; snapshots, tables, and charts to aid in explanations.
- Use pointers, callouts, or arrows pointing to each part of an active item.
- Organize document with easy to find information; use plenty of pointers, references, tips, thumbnails, etc to guide the reader.
- Make paragraphs short and succinct; use simple words and write for the audience.
- Use icons indicating relevant-must know information; warnings, advice, rules, policies, etc.
- Ensure plenty of white space.
- Do not create lengthy documents; break it up into more than one.
- Limit varying fonts and colors for pointing out information.
- Use outlines, bullets, etc., for ease of readability.
- Apply headers and footers.
- Include Glossary, Table of Contents, Appendix, Index, Error section, Check List, or Reference sheet/card if applicable.
- Include a Q&A section.
- When instructing, create numerical step-by-step directions and include indented sub-levels if appropriate.
- Change up the style from one section to another, e.g., from one column to two, or have text flow around images for a change.
Try to create a visually appealing document using some of the above ideas. If you have more suggestions or ideas on how to make documentation more appealing, please leave a comment.
