Too many people think of software documentation as a project they will complete as opposed to a process they will establish. Software documentation projects almost always fail. They fail to meet the real needs of users. They fail to provide up-to-date information. They fail to deliver real business results. The key to creating great docs is to abandon projects and instead establish a documentation process. I explain the details of how you can accomplish this in the short video below. The tips I share in this video are what our most successful customers use to make software documentation a key part of their business strategy.

Without clear goals your software documentation is bound to fail. Recently we have started thinking of our documentation in two contexts: Documentation that provides a road map Documentation that removes roadblocks

Do you answer yes to any of these questions? Is your customer support group inundated with repetitive requests for the same information? Are your employees clamoring to find out the details of your company’s new policies? Do you need to efficiently and effectively train new clients on the use of your product? Do you need to train your employees on the technology products you use to run your business? Managing knowledge bases without an easy way for groups of people to access them can suck productivity out of your business. If your customers and employees are constantly scrambling to find the information they need you need to consider the hidden power of an online manual. Online manuals centralize all of your pertinent data for specific groups. Whether it is a customer support manual, an employee handbook, a research guide, a lesson plan, an employee hiring test or a product tutorial guide, online manuals can solve your problems of distributing information to a large or small audience. Compare this to what a lot of organizations are doing - locking their knowledge in PDF and Word files. Capturing your organization's knowledge in these formats makes that knowledge hard to access and hard to update.

We have all experienced the frustration of wading through wordy, unclear documentation, just trying to find the information we needed. For some reason some authors believe that we need to know the life history of an application before we are allowed to do anything with it. We created this video to show what life would be like if GPS units treated us the same way. Enjoy!

A question was recently posted on Twitter, "@donmcallister @podfeet opinions on what problems are best solved by/use cases for Mac apps such as ScreenSteps, Screenflow, Skitch, others?" We get that question a lot. We answered it in depth in a webinar we did last year titled "Video, Screencasts and Still Images - Using the Right Tool at the Right Time." But for those who are interested in a shorter answer, here it is. These are some simple rules that we use.

I read two articles recently. One article highlighted the technical communication work of a six-year-old while the other was by a professional journalist for a major online publication. One example communicated information clearly and concisely. The other talked in abstractions. Can you guess which was which? Anne Gentle of Just Write Click showcased some technical communication work from her friend's 6-year-old daughter. The aspiring instructional designer created a step-by-step guide showing how to create a Play-Doh apatosaurus. When you look at the results you might notice something - there are no words, just pictures.

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: