We hate software documentation that doesn’t have pictures. You would be amazed at how many professional technical writers consider pictures and screenshots an afterthought. This video will give you an idea of what we think of documentation that doesn’t use pictures.
Online manuals are awesome. They make accessing and updating information so much easier. But if you apply the old paradigm of PDF software manuals to the new medium of online manuals you get documentation that is cumbersome to write and cumbersome for your users to use.
The biggest mistake we see companies making when authoring their documentation is misunderstanding the relationship between scope and detail in their help articles. The principle they are violating is the Goldilocks principle (part of our 5 keys to great software documentation). They either deliver too much information or not enough.
In today’s Docs that Rock Whiteboard video I discuss scope vs. detail in software documentation and how keeping these two concepts clear in your mind can help you write better docs that will help your users and drive product adoption.
If you want to see a funny example of dumping too much information on your customers then check out our Chatty GPS video.
By the way, we are going to be releasing a full series of Docs that Rock Whiteboard Videos over the next couple of months. These were inspired by SEOmoz’s Whiteboard Friday videos which, if you haven’t checked them out yet, are awesome.
If there are specific topics you would like us to cover in this series, please let us know in the comments.
As I wander the web I run into a lot of organizations that try to use user forums for software documentation. This is a big mistake. It creates a poor experience for your users and sets your organization up for customer support headaches. Software documentation and user forums have different purposes and need to be treated differently if you are going to deliver superb customer support.
We love software documentation. We think it is really, really important. But even we would be hesitant to claim that your software documentation could get you a better review from a major technology publication.
That is, until recently.
Over the past couple of months two ScreenSteps Live customers, BaseKit (5 stars) and RunRev (4 stars for their LiveCode product) have had their documentation mentioned as one of their “Pros” in MacWorld reviews (see the images below). The “Pros” is a section at the top of the review that points out the 2 or 3 best things about the application. In both these cases the reviewer felt that the software documentation created by these companies was one of the most important benefits of their respective applications.
About a month and a half ago I posted an article titled “Moving Beyond Customer Support: Focusing on Customer Success”. I’ve received a lot of emails form people saying how much they enjoyed the post and how they are dealing with those same issues in their business.
So today I wanted to give you an update on what we have done, what has worked and what hasn’t. With anything like this, experimenting and collecting data are very important. Without data you are just guessing about whether your changes have helped or not.
We track two very important numbers regarding ScreenSteps Desktop, number of trial downloads and number of purchases. Because we don’t require any user information to download a ScreenSteps Desktop trial we can’t map a specific download to a purchase. But over the last seven months the percentage of downloads to purchases has been pretty consistent. Our download to purchase ratio over the 7 months prior to Feb 2011 was 25%. Roughly one quarter of the people who downloaded ScreenSteps purchased it. We made one important change that boosted this conversion rate from 25% to 40% (a 60% improvement). Here is how we did it.
Our theory was that if we could help users accomplish a meaningful task with ScreenSteps right out of the gate we could improve this percentage. To do this we looked at our demo download page.
Today we are happy to be able to show you a new look that is coming to ScreenSteps Live support sites. Since we first launched ScreenSteps Live we have learned a lot about how users want to browse documentation as well as how our customers want to customize their ScreenSteps Live sites. For the past several months we have been working to create a simple ScreenSteps Live template that met the following goals:
After a lot of long nights we are very happy with the results. We think you will be too.
We know that our users want to create beautiful documentation with a minimum of fuss. The new ScreenSteps Live template has a very pleasant styling that helps you look great right from the start.
With this new release we really wanted to focus on discoverability. It has always been really easy to search your documentation on ScreenSteps Live. We wanted to make it easier to browse. We have added a new chapters sidebar widget that displays all of the chapters for the current manual making it easy for your users to browse your ScreenSteps Live site.
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?
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:
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.
Free eBook: 5 Keys to Successful Documentation
Just read this quote over at Signal vs. Noise by Ed Catmull, President of Pixar,
We all know the saying it’s better to ask for forgiveness than permission. And everyone knows that, but I think there is a corollary: If everyone is trying to prevent error, it screws things up. It’s better to fix problems than to prevent them. And the natural tendency for managers is to try and prevent error and overplan things
“Preventing error” is the biggest impediment to great software documentation. One of the first questions many customers ask us is “How can we make sure that changes are approved before they are published?” This is the wrong question. Organizations believe that software documentation needs to be “proof read” and “peer reviewed”. If each change to your documentation has to go through that process then your documentation won’t ever get changed.
Your first question should actually be, “How can anyone on my team update my documentation at any time?” Your documentation needs to change. Often. Any barriers you put in place to prevent this will come at a huge cost to the usefulness of your documentation.
Unless you are documenting something that has to do with life or death or you have to comply with legal requirements stop being a control freak. Let any of your employees update your documentation at any time. If they write something that is wrong, fix it. It’s not that big a deal. If you can’t trust your employees to be responsible with your documentation then get new employees.
Putting up barriers to changing your documentation hurts your business. At the end of the day, stale, out of date documentation is much worse than a typo or two.
Learn how to get better results out of your software documentation:
About a year ago we hosted a webinar on software documentation. 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”.
An Octopus graphic is a screenshot that has been abused by the ScreenSteps sequence tool or other image annotation tools. Look at the graphic below:
Octopus graphics have many, many labels describing different buttons (obviously we have exaggerated a little in the example above). This seems to be a popular approach among technical writers which we feel delivers very little value to end users.
Listing the names of buttons is of little use. This function can often be handled by a well placed tool tip in the interface. It is much more important to teach your users how to accomplish tasks. If you are teaching tasks then you will very rarely need octopus graphics.
With so many labels on the screen it is impossible to process what is going on. If you really feel that you need to label every button in the interface at least break up your labels into different graphics. Try to group the buttons into meaningful collections. People are better able to understand and retain information when it is put into smaller chunks. I would suggest limiting yourself to no more than 5 labels on a single screenshot. A single graphic with a bazillion labels on it presents information in a way that is hard to understand and even more difficult to retain.
If you use octopus graphics you run the danger of “documenting” your entire application without delivering any real value to the end user. Once you have labeled everything you may think that you are “done” with your documentation. But your documentation won’t deliver any business value to your organization. Your documentation shouldn’t be “done” until you have helped users accomplish real-world tasks. Octopus graphics don’t help people accomplish tasks.
Do you have a lot of screen captures that look like this in your documentation? It is probably a sign that you aren’t taking the right approach to writing your docs. You are spending too much time talking about buttons and labels and not enough time talking about tasks. Start creating more “task based” documentation and you won’t feel the need to create any octopuses.
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. In the upcoming weeks we are going to post a series of tips for capturing images that improve the effectiveness of your documentation.
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. Too much visual information will cause them to have to “study” the screenshot. Not enough visual information will force them to hunt through the application interface.
There are a variety of factors that can contribute to clarity, but in this article we are going to focus on size. If you get the size of your screen captures right then you will make big improvements to the effectiveness of your software documentation.
First, let’s talk about the goal for our documentation example. In this example we want to show the user how to export a lesson to the clipboard in ScreenSteps. To do this they will need to click on the Clipboard icon. An example is shown below.
Size errors come in two flavors, too big and too small. Let’s look at both.
Screen captures that are too big communicate too much information. By showing too much information it makes it difficult for the reader to discern what is important.
This first example captures my entire desktop.
The problems with this image are obvious. I have captured so much of my screen that the Clipboard icon is hardly visible. The extra data doesn’t add any value to the screen capture. It doesn’t add clarity. It just adds confusion.
The type of screenshot shown above is much more common. Capturing an entire window is easy and it looks nice and clean. But the only thing I need to show in my documentation right now is the Clipboard icon so this is still way too much visual information.
This approach to adding images to software documentation is very common:
What is the problem with this? You are asking your user to play “Where’s Waldo” with your software documentation. No context is given to help the user know where the Clipboard button is in the interface. Depending on the complexity of your application interface, finding the icon you are documenting can be like hunting for a needle in a haystack.
Why do authors do this? To save themselves the hassle of having to update their screenshots when their application changes. The thinking goes: “If I only have a picture of the Clipboard icon then it doesn’t matter where that crazy software engineer decides to put it. I don’t have to update my documentation.”
The amount of frustration you will cause your users simply isn’t worth the time savings. Don’t do this.
This is better but still not ideal. There is a little more context given around the Clipboard button but not enough to instantly communicate where the button resides in relation to the entire application interface.
Here is what I feel is an ideal size for the screen capture:
Notice two things:
We haven’t cropped the application window to remove the desktop background. Showing the borders of the interface help the user quickly orient themselves. Whenever possible, I like to get a corner of the interface in the screenshot. Including corners helps the user know if they should be looking top-left, top-right, bottom-left or bottom-right when following my instructions.
We include surrounding interface elements. Once again, we are trying to provide context. By including the surrounding elements I can give the user more “guide posts” that will help them locate the Clipboard button when actually using the ScreenSteps application.
I have worked with many technical writers who don’t like the look of this type of screenshot. They would prefer that the edges be tightly cropped for a nice, clean appearance. They are worried about aesthetics. I am mostly concerned about clarity.
Aesthetics will give you a very nice presentation piece to show your friends. Clarity will decrease customer support requests, improve user satisfaction and improve your business.
Blue Mango Learning Systems
© 2011
