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.

We have been using Zendesk to manage our help tickets for quite some time now. This last week we switched over to Zendesk for our customer support forums as well. As we were going to be pointing more of our users to our Zendesk site we wanted to customize the look a bit. The main thing we wanted to do was have easy navigation between our forums and our documentation on ScreenSteps. Using jQuery this is pretty simple. You can use the technique below to add any tab you like to your Zendesk support page. The full details of how we did this can be seen in our ScreenSteps Live API manual. In this post I will just go over the javascript we used.

In our recent webinar, Video, Screencasts and Still Images - Using the Right Tool at the Right Time, we spent a brief amount of time on the concept of Scope vs. Detail in your customer interactions. What do we mean when we talk about scope vs. detail? All communications have a naturally or arbitrarily enforced time/length constraint. The communication may be limited by several factors: The time the person is willing to devote to the communication The time the person is able to devote to the communication The attention the person is able to give the communication By being aware of these constraints you can adjust the scope and detail of your communications so that each communication can be "completed" in the available amount of time depending on willingness, availability and attention span.

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:

Using a web knowledge base to answer customer questions can be a tremendous resource. They are easy to access and easy to update. Most web knowledge base articles are text based, however. Adding screen captures or other visual elements to your knowledge base articles can dramatically improve the results your knowledge base delivers. Most people think that it is just because the articles are more clear (visual information makes instructions easier to follow). But they also affect the user's decision making when they are determining whether or not to read an article. Let's look at why that is. Knowledge bases usually contain "how-to" type articles. When a user views an article in your knowledge base they need to quickly answer two questions in their mind:

This is a follow up to the post from last week about pasting adjustments in Screenflow. A tricky situation can arise if you are pasting adjustments from a clip that has a video action on it. 3 Different Pan/Zoom Settings Here we have two clips but there are actually three pan and zoom settings. There is the initial pan and zoom setting of the first clip. This consists of the x/y coordinate of the video and the zoom setting. Next we have a video action. All a video action does is allow you to set a new x/y coordinate and zoom setting for the clip. The video action then animates the transition between the original pan/zoom setting and the new pan/zoom setting to create the pan/zoom visual effect. The new clip has its own pan (x/y coordinate) and zoom setting. Let's say that we want to copy the zoom settings from clip 1 to clip 2. At the beginning of the clip (1) the zoom is set to 100%. At the end of the clip, after the video action the zoom is set to 300%. At the beginning of the 2nd clip (3) the zoom is set to 100%. What we want is to change the zoom setting of the 2nd clip (3) to 300%. The Wrong Approach Here I have placed the playhead at the end of clip 1. What I will see on the screen is a zoom of 300% because I have the playhead placed after the video action. So I might think that I am copying a zoom setting of 300%. BUT I AM NOT. The Edit > Copy command copies what is selected, not what is under the playhead. If I copy right now I will be copying a zoom setting of 100%. The Right Way Now I have the video action selected. If I select Edit > Copy I will be copying a zoom setting of 300%. Finish Now just select the 2nd clip and choose Edit > Paste Adjustments > Video and you will be applying the 300% zoom to the 2nd clip. Improve Your Customer Commnunication