Creating Graphics For Engineers & Other Techies

Last time I talked about writing for technical types, continuing a discussion started by Michael Stelzner. Now let’s talk a bit about creating graphics for engineers, programmers, and scientists. 

Too often, graphics are created at the end of the project, close to the final deadline, when the text is nearly complete. The graphics that ultimately are produced are not always the ones that should be produced — they’re the ones that could be completed in the time available. And they’re not proofed nearly as well as they ought to be. Graphics need more attention than that, especially when they’re intended for this target audience.

• Bulletproof diagrams for workflow, process, and so forth before you publish them. Have a resident techie look them over before you release a document. This group pays a lot of attention to diagrams and they themselves draw them very well. If there’s a lapse in logic, they’ll find it. 
• Create and include a legend of the colors and line styles you use in a diagram and stick to it.
• Create a style guide to help ensure consistency between graphics within a single document and within a collection of documents. It drives this audience nuts if, say, a thick green dashed line appears to mean different things in different documents.
• Ensure graphs and charts fit your data and the story you’re trying to tell with it. I’ve seen engineers get caught up in 20-minute debates about whether a bar chart was really what an author should have used to show XYZ data.

If you’re writing about software, review your screen shots. As a tech writer, it never ceases to bug me when I pick up a user or admin manual and find screen shots that were clearly never proofed.

• Make sure there’s a clear connection with the text. If the screen shot correlates with a step in a procedure, position it near its text. If the screen shot correlates with something in a paragraph, include a clear reference to it (e.g., “See Figure 1-1″).
• Ensure that command lines, directory paths, data inputs in fields, and lines of code in config files or scripts shown in screenshots are correct and, where relevant, consistent with anything discussed in the main text of the document.
• Make sure the screens are correct for whatever software you’re talking about (yours, an operating system, an RDBMS, etc.) and whatever version of that software you’re talking about.
• The same goes for writing documentation for physical devices (computers, printers, stereo equipment, etc.). Make sure photos and technical drawings show what they should.
• Proof for typos and misspellings. 

This is all common-sense, you-should-always-do-this-for-any-reader advice. But I’ve observed that where other readers may just quickly glance at images, techies will scrutinize them.

I’m sure there’s more. If you’ve got ‘em, share ‘em!