Just came across an interesting presentation by Cheri Lockett Zubak via Anne Gentle’s “Great State of the Union for Tech Comm” post. Cheri’s presentation is titled, “Developing Content as a Business Asset”.

The presentation follows a User Assistance Group at an imaginary company as they try to explain to their President why their group is an asset to the company. I was clicking through the slides and came to this one:

I was quite surprised when I clicked the arrow and found that it took me to our webinar on software documentation. The title of our webinar is “Why Your Documentation Stinks and How to Fix It.”

Apparently, Linda, the protagonist in this story, didn’t like the webinar.

(more…)

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).
• 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 and delivery system a bit.

It’s 2010. Your primary tool as a technical writer should be a camera, not a typewriter, regardless of your learning style.

Just read a good post by Tristan Bishop titled “What if no one READS the manual?” Click through to read all the details but the gist is that technical writers need to become more engaged with end users. This is exactly along the lines of what we said in our post about who should write your software documentation.

Bishop is correct. Many technical writers are going to face challenges in the upcoming years. They will increasingly be judged on the effectiveness of the content they create as opposed to the quantity of that content. As Bishop says:

• The anonymity of our job? Gone.
• Lack of external accountability? Gone.
• Quiet days building intricate books alone in a room? Gone.

Technical writers need to get closer to end users. They need to stop thinking about documentation projects and realize that they are in a communication flow where documentation constantly needs to be created and updated. Speed and an ability to adapt to changing circumstances will be the key skills needed for technical writers in the future.

So where are you at? Do you know how effective your software documentation is? Do you know if anyone is reading it? Do you know if it is decreasing support requests or improving product adoption? If you don’t know then you should find out quickly because pretty soon the next question will be “Are you a necessary part of this organization?”

If you need some ideas for improving the usefulness of your documentation check out our article, “5 Steps to Improving Your Software Documentation”.