Dallas-Fort-Worth (DFW) Texas based Brandfocal provides Technical Writing services.
As a technical writer, your job is to convey information to your readers. Sometimes the best way to do that is by writing long descriptive passages. Sometimes the best way to do that is by providing short, easy to use procedures detailing precisely how to perform important tasks. But sometimes you need to provide a screenshot or a graphical representation of an idea before it can really gel for your readers. Part of your job is judging when to rely solely on words and when to provide a graphical illustration of the information you need to impart to the reader.
Using tables
Many people today think of tables as layout tools, tools to help present information in pretty columns. Although tables are often misused in this fashion, they are not meant to be an underlying layout tool. Rather, their purpose is to present tabular data clearly and understandably.
What is tabular data? Tabular data is any collection of data that most logically fits into a matrix. This is most often a series of elements which each have multiple properties. For instance, you could have a series of error codes and their corresponding text messages. You could present these as a list, but if you present them in a table you don’t need as many descriptive words and the two parts of each error – the code and the message – are visually separated and easy to identify at a glance.
To illustrate this example, let’s display a list of errors and then a table containing the same information. First the list:
- Error 190 occurs when you run out of memory
- Error 200 occurs when your input value falls out of the allowed range
- Error 300 occurs when you cannot connect to the database
And now the table:
| Error Code | Error Message |
| 190 | Out of Memory |
| 200 | Out of Range |
| 300 | Connection Error |
As you can see the table is a lot easier to parse. Imagine if each of the elements in the collection had four or five different properties. In this example, the errors could also be categorized by error type and you could also note whether the error message can be localized. The list would get a lot more dense and convoluted, while the table would remain relatively easy to read:
- Error 190 occurs when you run out of memory. It’s a basic system error that can be localized.
- Error 200 occurs when your input value falls out of the allowed range. It’s a parameter error that cannot be localized.
- Error 300 occurs when you cannot connect to the database. It’s a basic system error that cannot be localized.
or within the table:
| Error Code | Error Message | Error Group | Can Be Localized? |
| 190 | Out of Memory | System | Yes |
| 200 | Out of Range | Parameter | No |
| 300 | Connection Error | System | No |
As you can see, tables really do make a big difference. Use them judiciously, but use them whenever you need to present a collection of tabular data.
Using screenshots
Sometimes, a picture really is worth a thousand words. No matter how well you describe the user interface of a product, there’s really no replacement for showing your users what it actually looks like. You need to describe things too – screenshots aren’t a replacement for proper discussion – but sometimes an illustration can help your text make more sense.
As with tables, you don’t want to overuse screenshots. If an entire section is devoted to the same tab of your application, you generally don’t need to present a visual image of that tab every time you ask your users to do something within that tab. If you present the same picture six times within a single procedure it merely serves to slow down the process, spread the information out over multiple pages, and interrupt their train of thought.
In general, unless they are small graphical representations of buttons or active screen elements, it’s best not to include any screenshots or other illustrations within a procedure. Provide any necessary graphics before you get into the procedure so your users can refer to them as needed without having them interrupt the procedure itself.
Using representational drawings
Just as screenshots can help your users better understand procedures and how to navigate through the user interface of the product you’re documenting, representational drawings can help them understand conceptual material. Spending three pages describing the product architecture in detail is all well and good, but without a diagram showing how your application server sits above the database but behind the web-server, even a lengthy description may not register with your users.
Again, as with screenshots, representational drawings cannot take the place of the actual written discussion. Without text to frame the drawing your users won’t know what they’re looking at or why they should care. You need both elements working in concert.
Writing captions
Although not absolutely necessary, most product manuals provide captions for all graphics including drawings, screenshots, and tables. These captions provide a short catch-phrase that tells your users what they’ll be seeing in the graphic. It’s sort of an extra reminder of what they should be thinking about when they look at the table or picture.
Captions tend to stand out more than the general text surrounding the graphic so you can find a little bit of information about a graphic without having to scrounge around the nearby text. If you’ve arrived at the page to see that particular table or figure rather than to read the section of text, this can be a real timesaver.
Table of Figures and Table of Tables
Most books provide a Table of Contents to help readers understand what material is covered within the book and to help them quickly go directly to a specific piece of information they need. Many manuals also provide Tables of Figures and Tables of Tables for the same reason.
Usually found immediately after the Table of Contents, these two listings generally list the figures – screenshots and representational drawings – and the tables within the book using their captions as descriptors. These tables are not as widely used by readers as the Table of Contents or the index, but they do provide an alternate route to quickly find specific information throughout the book.
They also give the reader a sense of which concepts are most important in a book. Because the Table of Contents lists everything within a book, it doesn’t give you any sense of what the key areas are. It’s all listed and treated equally. But if a concept is important enough to warrant a representational drawing the reader knows it’s something you particularly want them to understand well.
I personally don’t like Tables of Tables; unlike the graphics which can tell you which concepts are important, the tables merely indicate that you need to present sets of data that best fit into tabular form. In addition, most books have a lot of tables and it’s very intimidating to start a book with pages and pages of listed tables. It also sort of defeats the purpose (pointing out important information) when you’re pointing out half of the book.
Summary
Graphics – screenshots, representational drawings, and tables – are an important part of technical writing. The key is to use them appropriately. Determine when they are needed and when they aren’t. Make sure they fit the topic you’re discussing and that you provide a short but informative caption for each graphic. Most importantly, make sure that you don’t add graphics just for the sake of having pretty pictures in your manual.