We obviously talk a lot about using images in software documentation. When I speak to technical writers I will often get a response that is something like this: Pictures work for certain learning styles. But some people are auditory learners and some people do better reading text. Bunk! It simply isn't true. I, like everyone else, have heard about this theory of "Learning Styles" for quite some time. Turns out this is one of those "truths" that we all accept but that doesn't have much proof to support it. Here is a quote taken from a recent New Your Times piece: Take the notion that children have specific learning styles, that some are "visual learners" and others are auditory; some are "left-brain" students, others "right-brain." In a recent review of the relevant research, published in the journal Psychological Science in the Public Interest, a team of psychologists found almost zero support for such ideas. "The contrast between the enormous popularity of the learning-styles approach within education and the lack of credible evidence for its utility is, in our opinion, striking and disturbing," the researchers concluded. By claiming that there are many learning styles and that some people learn better by reading, technical writers claim that a text-only format is an acceptable form of software documentation. Take a look at the documentation example in this post. Can you show me one person who would prefer the text only version to the version with pictures? The Real Issue: Work Talking about "Learning Styles" in software documentation is really just a red herring to move our focus away from the real issue: work. Adding images to documentation takes extra effort and can add complications to the delivery process. Some of the problems include: Technical writers may not be comfortable with image capture and image editing software. Adding images to documents is often clunky and cumbersome (though we believe we have a [pretty good solution for this][3]). It is more difficult to translate a screenshot than an xml document into multiple languages. Updating your documentation with changes takes more time and effort if you use screenshots. The Benefits Outweigh the Costs But the benefits far outweigh the costs. By adding images you add a level of clarity that is simply not possible with the written word. And clarity delivers real business results. I spoke with one of our customers the other day who estimated that they had already saved $10,000 by creating a single visual document. All this document did was show his customers a checklist they had to go through before they returned a very expensive piece of equipment for repair. The document had pictures for every step of the checklist. Guess what happened? Their return rate dropped. Customers found out that their equipment wasn't broken before they sent the equipment back, saving the company shipping costs, expensive tech time as well as downtime at the customer site. If you aren't using visuals in your documentation then stop hiding behind this false notion of "Learning Styles." Address the real reasons you or your organization are avoiding visual documentation. Most of them are solvable if you just rethink your workflow, delivery system and your documentation software. It's 2010. Your primary tool as a technical writer should be a camera, not a typewriter, regardless of your learning style.

About a year ago we hosted a [webinar on software documentation][software-webinar]. During the webinar we showed an image annotation technique that is very common and, in our opinion, very ineffective. One of the participants in the webinar said they called the type of image an "Octopus graphic".

We obviously believe that adding screen captures to software documentation makes a huge difference. We would go so far as to say that it is the difference between software documentation that produces business results and software documentation that creates door stops. But simply adding pictures isn't enough. You have to add the right pictures in the right way. When we add screen captures to our software documentation we have one goal in mind: clarity. Clarity is all that matters. I want my reader to be able to quickly glance at the screenshot and move on. I want them to only have to process as much visual information as is absolutely necessary.

In his post, “'Digital Natives' and the end of traditional hotline support”, Ellis Pratt describes how the model of support has changed from the 1990's. In the 1990's users would seek immediate support from people who were geographically near them (usually in the same office or workspace). With the advent of social media, geography is no longer important. Users, especially younger users, are first turning to Google, Twitter, email, instant messages and other forms of social media to get answers to their support questions. These forms of communication are almost uniformly text-based. Where does traditional software documentation fit in this new process? Quoting from Ellis:

Many businesses have a Technical Publications department that is in charge of writing software documentation. Most customers never read software documentation. Those two facts are directly related.

Today's software company, whether providing desktop or SAAS offerings, provides customer support in a number of different settings. For example, in our company we interact with our customers in five different ways:

I don't ever plan my documentation. I used to. But not anymore. It's a waste of time. Maybe if I were on a documentation team and had 6 months to get the documentation ready then maybe I would plan. I could plan and then revise and then plan some more. But I am not on a documentation team. I run a business. I am the web programmer, accountant, custodian, sales person, system admin and business development director. I don't have time to plan my documentation. So what have I done? I have planned not to plan. I have created a system for documentation that requires no planning at all AND creates documentation that is much more useful to our customers. It really is quite simple. Just follow these simple steps: