OK, don’t fault me for the title; tech writing topics are boring to most people so a spicey title is sometimes needed.
Besides, this post actually IS about graphic content–just, the kind you find in software documentation.
“A picture paints a thousand words”
If this saying is true, why are so many authoring teams in the high-tech software industry purging them from their docs? Removing graphic content is trending, and there are lots of reasons why they are disappearing.
Cost to maintain and cost to translate top the list — with the latter being the more expensive. As does the concern that a diagram or screenshot may prevent a topic from being reusable in other content. And of course, working with graphics is not the comfort zone of most authors. Observe the shudder that the prospect of creating a diagram in Microsoft Visio can cause even seasoned authors.
So.. should we scrap them all? (graphics, not authors)
If it’s truly cost that is really the main concern, it sounds like we should. But is there a cost to removing them? I don’t mean the manpower to do it, I mean their communication value.
- Were not some diagrams created because they could instantly communicate sophisticated relationships between components?
- Were not some graphics created to give users a visual that could be recalled far more easily than pages of theory?
- Were not some screen captures created because despite our best design efforts, poor User still misses some vital clue on a screen?
- If we remove the really valuable graphics, are we not then shifting costs from the authoring camp to the support camp?
Whacking all graphic content certainly solves ‘fast’ and ‘cheap’ in the “good, fast, cheap” project management triangle, where you can presumably only satisfy two of those goals at any given time. But maybe we can still retain some good.
Keeping cost and clarity in focus, what if we ensured our graphic content adhered to the following criteria:
- Screenshot: Draws User’s attention to some recondite behavior in the UI (for example, something they wouldn’t realize they can click on) that can benefit them, or cause undesirous effects if not perceived. (http://dcx.sybase.com/index.html#sa160/en/dbusage/ug-appprofiling-s-5023070.html)
- Screenshot: Illustrates an example of an end state of a complicated screen. For example when there are many things to select and do, we want to give User a visual confirmation they’ve done things right. (http://dcx.sybase.com/index.html#sa160/en/dbusage/ug-appprofiling-s-5023070.html)
- Diagram: Illustrates complex relationships between components, where the picture would replace a thousand words. http://dcx.sybase.com/index.html#sa160/en/dbadmin/charset-conversion-client-apis.html)
- Diagram: Delivers a visual that User can draw from and return to while working. (http://dcx.sybase.com/index.html#sa160/en/uladmin/cast-function.html)
- Any graphic: Helps avoid a support call, and/or the loss of User’s data.
Wouldn’t this strategy keep all costs low while also continuing to meet the needs of User?
To sum up…
Software documentation can sometimes benefit from graphic content, and it’s important to realize that there are costs associated with having them as well as with NOT having them. Keep costs down and User happy through rigorous, judicious evaluation of each graphic, revisit your decisions at each major release, and resist the urge to purge for ease’s sake.
PS> The SQL Anywhere documentation has already undergone several such evaluations over the last 3 major releases, reducing our graphics count by 3/4. We now maintain about 200 graphics across 14k topics. But in researching for this article, I’ve spotted a few more that don’t really add much and can be removed..