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.

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”.

What is 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.

What are the problems?

1. Octopuses describe features not tasks.

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.

2. Octopuses are cluttered.

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.

3. Octopuses make you think you are done before you actually are.

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.

Throw Out the Octopus

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.

The goal

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.

Too big

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.

Still too big

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.

Too small

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.

Still too small

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.

Just right

Here is what I feel is an ideal size for the screen capture:

Notice two things:

1. 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.

2. 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.

Focus on what matters

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 ascetics. 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.

We talk a lot about software documentation on this blog. But running a business requires much more than just software documentation. Documenting business processes is a simple investment that can pay big dividends. By establishing a simple system for capturing and retrieving your business process documentation you can really improve your organization.

Good process documentation has saved us literally 10’s of thousands of dollars by allowing us to do more with fewer employees. But sometimes people don’t know what to document. They think they only need to document “big” things or things that they do frequently. We have found the opposite to be true. The most important things to document are the little things we do infrequently.

Here are 10 examples of things we document that have saved us a lot of time:

1. How to file our quarterly or annual tax forms. A lot of this is done online. I don’t know about you, but our forms are a little cryptic. Documenting this process turned what was usually at least an hour of work into about 5 minutes. Also, I no longer procrastinate the job and thus avoid flirting with late fees.

2. Importing CSV files. About once a week we have to import CSV files from our marketing analytics software to our CRM software. Before the data can come across it needs a little “massaging”. Documenting this has cut a 15 min. process down to about 3 min. and also prevents me from having to deal with bad imports because of mistakes I made in the import process.

3. Issuing refunds. We have a 100% percent money back guarantee on all our products. Fortunately, our customers very rarely ever ask for a refund. But documenting this process for the few times that it does happen has allowed us to process refunds almost instantly. The customer may not have been happy with the product but at least they go away with a positive impression of our organization.

4. Accepting wire transfers. Some or our international customers pay via wire transfer. It happens infrequently but documenting the process means we can get them the information they need right away when that is the only payment option available.

5. Preparing invoices for special situations. Every so often we have invoices that we have to prepare that don’t fall into the standard categories we bill for. It might be some custom work or a special way a reseller needs to be invoiced.

6. Downloading banking transactions. Unfortunately, each of our banks and credit card companies has a slightly unique twist on downloading transactions into our accounting software. Documenting this process saves us time, but more importantly, it gives us less excuse to procrastinate this necessary but dull task.

7. Setting up webinars. Every couple of months we will do a webinar. Documenting how to set up a new webinar helps us focus more on creating great content than dealing with the mechanics of running a webinar.

8. Installing WordPress on our servers. Installing WordPress is pretty easy. But remembering the unique details of how to do it with our hosting company can be a little tricky. After documenting it once it is a breeze to do.

9. Configuring a new computer. Everybody likes getting a new computer right? But getting everything set up can be a pain. Documenting some of the custom settings that need to be made for your work environment or network will make sure that you can add a new system with a minimal amount of pain.

10. Renewing our SSL certificates. This only needs to be done once every couple of years but the instructions our certificate provider has on their site are not very helpful. Documenting this process makes sure we don’t mess up our SSL certs.

All of the items listed above are tasks that we only occasionally perform. Those are the most important processes to document because they are the processes that are hard to remember. Add a little more process documentation to your business and I promise you will see big improvements in productivity.

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”.

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 form 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:

So what’s happened to the manual – where does that fit in?

In many cases, the manual is now a collection of Web pages. It’s moved up to the top of list, although many may not recognise it as a manual. It might not have an index, page numbers or a table of contents, but it serves the same function.

Ellis is correct. Users are looking for help on the web. If your software documentation is locked inside of a PDF file then it is essentially non-existent to today’s users.

Ellis makes some very good points in his post but I think he draws the wrong conclusion in the end:

If companies want to sell to “Generation Y” , they will need to ensure the ways they assist their users reflect this preference for text-based content.

“Generation Y”, or any generation for that matter, does not prefer text-based content. They prefer to communicate with tools that only allow for text-based communication. This is a subtle but important difference.

Putting the Customer Help Desk on Twitter and Online Chat

We quite often will provide customer support via Twitter or a online chat system that we offer via our website. These are text-only delivery systems. We can’t include images or videos. But we can provide urls.

Our ScreenSteps Desktop and ScreenSteps Live documentation has been optimized for use in this exact situation.

1. The documentation is broken up into small bits that answer a single question.
2. The documentation answers “How do I” questions which are the types of questions we receive in support.
3. Each section of the documentation has a unique url that we can share in Twitter, chat, email or forums.

Though we are communicating in a text only format, we are providing image-rich communication that better answers our users’ questions.

For example, if a customer asked us, “How do I set up a custom domain on my ScreenSteps Live account?” our response might look something like this:

Just follow these instructions: http://bit.ly/9B1WWU

The answer is concise and easily comes in under 140 characters (you can see how we have structured our help system here).

As Ellis states in his post, “Essentially, people followed the easiest path to solve their problem.” For many users that involves asking and answering questions via text-based communication. Make sure that your help content is optimized for sharing in that format and you will dramatically improve the results you get from your software documentation.

Check out our post, “Online Help Documentation – 5 Keys To Making It Work” for more tips on how to author, format and deliver your documentation.

Photo by geishaboy500

We obviously create a lot of documentation. People often ask us what tools we use. Here is a quick rundown of the tools we use on a regular basis to create our documentation.

• We use ScreenSteps and ScreenSteps Live for creating and publishing our documentation.
• For creating video we mostly use Screenflow. It is a great combination of both screen recording and editing. If we don’t need to do much editing we will occasionally use iShowU.
• For creating flow charts or process diagrams we use OmniGraffle. It is a fantastic tool for creating simple or complex diagrams. We also have a simple method for getting OmniGraffle diagrams into ScreenSteps.
• If we need to do more detailed image editing than what is available in ScreenSteps then we use Photoshop or Acorn. We use these tools if we need to remove or blur parts of an image or somehow doctor it to look different than the original capture.

That’s pretty much it. What tools do you use?

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.

Technical Publication Departments Are Ill Equipped to Create Software Documentation

Tech Pubs have almost no interaction with actual users. They create “requirement” documents from the various stakeholders (marketing, compliance, engineering, sales, service, support, etc.) and then create documents that meet those requirements.

Unfortunately they rarely ask users what they need.

This lack of direct connection with end users means that tech pubs has no idea what information is actually important to their users. They don’t know what questions the users have. They don’t know how best to answer those questions. The end result is software documentation that meets the requirements of “stakeholders” but not users.

Guess what? The stakeholders aren’t going to use the documentation.

Your Customer Help Desk Has the Questions and the Answers

The people who are best equipped to write your software documentation are those that are working the customer help desk. They may not have training in technical writing but they know exactly what the most important issues are for your users. They know what questions need to be answered. They know the real answers to those questions.

Have your help desk people write your software documentation. Their daily interaction with users will help them write documentation that is much more useful.

We have seen some changes recently in how our customers are using ScreenSteps that are very interesting. ScreenSteps for a long time has been used mainly to create software documentation for single applications. But now we are seeing more and more customers using ScreenSteps to support the integrated use of many applications.

This is an interesting development in several ways and shows what challenges small businesses, non-profits and educational institutions are facing.

Applications in general are becoming more modular in nature. Looking at our own business, we use separate applications for:

• Help desk
• Online knowledge base
• Email marketing
• CRM
• Project management

We much prefer this approach because instead of getting one app that does a lot of things “kind of well”, we get several apps that do one thing really well.

But this also presents a challenge – integrating all of these apps into a consistent workflow that works for our business. The vendors of the various applications can’t possibly provide documentation on how we will use these products together. If that documentation is going to exist we need to create it because it only applies to us.

For a long time we have used ScreenSteps and ScreenSteps Live to help ourselves make better use of the technology we purchase. We create documentation that is primarily for internal use. This benefits our business in a variety of ways:

• We spend less time re-learning workflows
• When someone is not around it makes it easier for other workers to take over their responsibilities.
• It makes it easier to add new people to our team on a temporary or permanent basis.
• It helps us integrate the various products/services we use more efficiently.

When we first launched ScreenSteps we were telling a lot of businesses that they should be following this same method of documenting things internally, but our suggestions seemed to largely fall on deaf ears. The companies we were talking to were interested in creating documentation for their customers, but not their employees.

But over the last few months we have really seen a change. We are talking to many more customers that are primarily using ScreenSteps to support their internal employees. We recently did a case study on Jenna Baze at Aero-Metric, Inc. using ScreenSteps and Google Sites to support her colleagues on Salesforce. Her primary job is to keep the sales team running efficiently. Good documentation helps their business run better.

We also did a case study on Judi Sohn at C3. Judi is using ScreenSteps and Google Sites to help her non-profit use Salesforce, WordPress, and other technologies..

We have also seen an uptick in interest from school districts and universities (one of the early adopters of ScreenSteps Live was Saddleback Valley Unified School District who grasped onto the concept of building visual knowledge bases right away and has had fantastic results.)

All these organizations have faced the challenge of getting the maximum benefit out of the technology products they are using. They want to turn technology features into business results. Documentation is helping them do that. ScreenSteps is helping them create that documentation more quickly and more clearly.

We are seeing this shift on ScreenSteps Live as well. Previously we would only hear from users who wanted to use ScreenSteps Live to support external customers. The thought was that internal employees could somehow get by without the same level of support that customers needed. But in recent weeks I would say at least half or more of our ScreenSteps Live customers are starting to use ScreenSteps Live for internal help files as well as external facing material. We are also seeing an increase in users who are only using ScreenSteps Live for internal facing help files.

It is an exciting time to be a small business. There are so many tools available that help you accomplish quite a bit with limited resources. The trick is tying it all together. Creating clear and simple documentation that is specific to your business or organization, regardless of the documentation tool you use, can really help you get the most out of your technology investment.

It has been just over a week since we started our iPad documentation project so I wanted to give you a little update. So far we have just over 40 lessons posted. You can see the examples here: http://ipad.screensteps.com.

To determine our lesson material we have just written down questions that came up for us when using the iPad applications or things that we discovered that we thought would be non-obvious to most users.

The process for creating capturing images on the iPad and getting those images into ScreenSteps is a little different than what you would do for a desktop application. But the workflow we have developed has turned out to be pretty efficient. Here is what we did:

Screen Capture

To capture images on the iPad you press the Home and Power buttons at the same time. The screen flashes and an image is stored in the Photos application.

Most of the time a single person can handle this. But occasionally it can be necessary to have two sets of hands to get a screenshot. For example, this image where I am dragging slides around on the left can be a bit tricky with one person since you need one hand to drag the slides, one hand to press the Home button and another to press the Power button.

If someone else is around have them capture the image while you drag the image and it will be much easier.

NOTE: When you are capturing something like this where you are dragging slides or objects, the objects will snap back to their original locations when you initiate the screen capture. It will appear that you aren’t able to get an image of the screen while the drag is going on. You can. As the example above shows, the image gets taken before the objects revert back to their default positions.

Importing Images

Now that you have captured the images you need to get them off of your iPad and into ScreenSteps. If Photos is set to sync with your iPhoto application then your screenshots will start showing up in your iPhoto albums. That isn’t what we wanted. Instead we used Image Capture, a handy utility that you can find in your Applications/Utilities folder. With Image Capture you can selectively download images to different folders on your Mac as well as directly delete the images from your iPad.

On our Macs we created folders for each lesson we were creating. We would then use Image Capture to import the images we needed into those folders. You can keep your iPad connected while you are capturing and importing images. This makes the whole process go very quickly since you don’t have to keep re-syncing the iPad to get your images.

As the Image Turns

We found that we took most of our screen shots in landscape mode. This means that the images will come in sideways. ScreenSteps doesn’t have a tool for rotating images so we setup an Automator script that would rotate the images 90 degrees.

Authoring and Publishing

At this point our images were all prepared. We then created a new lesson in ScreenSteps and dropped the images from the Finder onto the lesson in ScreenSteps. ScreenSteps imports all of the images and creates a new step for each one. At that point we just needed to crop, add annotations and text and the lesson was done.

We set up separate manuals for each application on ScreenSteps Live. Once the lesson was completed, we published it to the appropriate manual on the ScreenSteps Live site.

Recap

So, to recap the whole process went like this:

1. Capture images on the iPad
2. Create a folder with the lesson name on the Mac.
3. Use Image Capture to download the images to the folder.
4. Use Automator to rotate the images.
5. Drag the lessons in the folder onto a new ScreenSteps lesson in ScreenSteps Desktop.
6. Author just like we would any other ScreenSteps lesson and post the results to ScreenSteps Live.

Though the screen capture tools on the iPad may not be anything fantastic, they are clearly good enough that you can create visual step-by-step guides fairly quickly if you implement the right workflow.

Update

Here a few of the best examples:

• Keynote for iPad: Using Magic Move
• Keynote for iPad: Grouping slides
• Numbers for iPad: Copying a formula across multiples cells
• Pages for iPad: How to mask an image
• How do I set up Gmail on my iPad to send from a non-Gmail address?
• How do I add an address in an email message to my Address Book?