The State of Documentation, Part 3
By Bonnie Roskes, P.E., October 16, 2002
This is the third article in a three-part series on CAD software documentation and training. This is a topic rarely covered in any publication, but it is one that affects nearly everyone in the CAD industry - those who use CAD software, those who make CAD software purchasing decisions, and those who produce CAD software. Comments are welcome: firstname.lastname@example.org.
In Part 1 of this series I focused on the benefits of producing quality documentation; in Part 2 on the reasons documentation often suffers. In this article, I will discuss the main types of software documentation, and analyze the usefulness of each.
How Documentation Can be Better
You can’t please all users all the time. Some want a printed book, some want to press F1 for an instant answer, and some like to watch video demos and tutorials. During the course of my career in software documentation, I have found that no matter what the software, there are some constant truths governing documentation - truths that often elude CAD company decision-makers. Here’s a look at the main forms of software documentation - manuals, online help, tutorials, and demos.
Manuals Nobody really wants to read a manual and rarely are they read cover to cover. Manuals are generally opened only when there is a problem. Given this fact, manuals are most helpful when a desired piece of information can be easily located, digested, and understood.
What is the best way to make information “findable?” A table of contents is pretty, easy to generate, and gives a nice overall picture of what’s in the book. But when was the last time you used a book’s table of contents? Perhaps to check whether 3D modeling is covered in chapter 14 or 15, but not to find anything more specific than that. When you want an explanation of how to draw a spline, you invariably turn to the index. Unfortunately, indexes usually contain only about 10% of the entries they ought to include. A good writer should pore over all content with a fine-tooth comb and furiously add index entries, figuring out every possible way a user would search for a particular piece of information. “Spline” should be found under “Spline,” as a subtopic under “Drawing,” “Creating,” “Tools,” “Geometric Entities,” “Curves” - you get the picture.
Ideally, a manual is a series of short tutorials, heavy on pictures and light on text. Few want to read the fine print (or any print), and so a good writer relies on pictures to illustrate almost any task. This is especially true in CAD, which is more visual than most other applications. And if a mini-exercise will get you to actually use whatever tool you just looked up, there’s a much greater chance the information will stick.
Online Help The big thing in the tech writing world is “single sourcing.” This means writing the documentation once, then using this same set of files to produce at least two kinds of documentation, usually a printed manual and online help (OLH). (Normally, book files are created first and then converted to OLH, but the reverse can also work.) Single-sourcing clearly saves time, and budgets sometimes don’t allow for more than this one-step process. Online help and manuals, however, should be treated as two separate entities. Both can contain the same text and graphics, but they need to be presented differently.
OLH needs to be concise and precise. As with manuals, nobody wants to read reams of black text; most users don’t have the patience for much more than a few lines. They want short explanations, lots of hyperlinks, and LOTS of pictures. One advantage of online help over a manual is color graphics; printing in color is still prohibitively expensive but there are no such restrictions on help files. The ability to add animation is another plus.
Because nobody wants to scroll screen after screen when seeking a quick answer, online help pages should be extremely short. If a page contains links to other relevant topics or subtopics, these links must be immediately obvious, ideally located at the top of the page. In a perfect world, each online help topic would contain a very short video showing how to use the described command, tool, or option.
The simplest way to produce good online help is to start by single-sourcing. Write the book, then convert it to OLH. But this is not the end of the process; further work is necessary to shorten pages, add links, and restructure the order and contents. (Conversely, if the original source is in the form of online help, then the extra time would be devoted to restructuring the book.)
Tutorials Tutorials are, in my opinion, the best way to learn software. They are more helpful than a manual because they get you to use the software hands-on to build something from start to finish. Working through a good exercise will ensure that the concepts and tools stick, something not easily accomplished by reading text in a manual. That said, good manuals are still essential because no tutorial can ever cover every tool and option.
The key to a good tutorial is to make you create something while demonstrating a maximum number of tools and features. Beyond simply assigning steps - such as “Select the Offset tool” or “Enter 5.0 for the radius” - the steps must be explained: why was this tool used, what would be another method to achieve the same result, why a certain range of values should be avoided. If a tool can be accessed either from the menu, toolbar icon, or a hotkey, each of these methods should appear somewhere in the exercise. If there’s a long way and a shortcut to perform the same task, both should be demonstrated. A tutorial that does not get you moving the mouse and clicking and typing is really just a glorified user guide or online help.
Like any reference material, tutorials can be provided in a printed (or printable) or online format. Despite the advent of slick videos and interactive multimedia, the overwhelming majority of users still prefer print. Perhaps it’s because old habits die hard, but I think print is simply more comfortable to use. There is a certain level of comfort in placing your finger on the page of a book sitting next to the keyboard, performing the step, and returning to the page for the next instruction.
Online tutorials can also be effective, and they provide advantages similar to online help: color graphics and animation can be used, updates can be easily disseminated, and they require no extra shipping expense. The most crucial element here is that the screen size of the tutorial be sized to sit alongside the application itself. Nobody wants to continuously switch between windows. And, as in online help, pages should be small enough to avoid the need for scrolling. “Back” and “Forward” buttons at the bottom of each page are much more comfortable to use than scrolling down a long page.
When producing online tutorials, simple is better.
Animated Demos The latest trend in tutorials is to produce them as animated demos, using Flash or other slick multimedia. With all their bells and whistles, animated demos are a sexy and economical way to show off your software. But their effectiveness is questionable.
Some companies invest time and money providing numerous high-quality demo tutorials, showing users pretty much all they will ever need to know to use the software. But their tech support people still receive countless calls for basic operational issues. Somehow, the message is still not sinking in. Why?
Watching such a demo is entertaining and seems useful at the time. But when it’s over, and you return to your application, open to an empty file, you still don’t know where to begin. It’s very hard to watch a video and then recreate the scenario yourself. In some cases the videos are simply too long; after a minute or two you forgot how it began. If you don’t perform an exercise yourself, step by step, chances are you won't learn it. Some demos are self-paced to allow the user to proceed by mouse clicks. This is a step in the right direction, but there is still the problem of window-switching and remembering what to do when the animation has stopped.
Animated demos are perhaps better suited for use as marketing tools, to help potential customers engaged in comparison-shopping decide on the right CAD package. Although video may be entertaining, for the majority of users it's not the best tool for teaching. Interactivity is the key: if you want to learn it, you must sit down and use the software yourself.
As I said at the beginning, you can’t please all users all the time. Some users prefer a big book, some like online help, some like the cool videos. Everybody learns differently, and the decision to produce one type of documentation over another is a gamble.
First, make an informed decision about what your users want. I discussed user feedback in the first article of the series; asking users what kind of documentation they want works much better than just guessing. Once you've decided on a format, figure out the best way to set up the documentation to benefit the most users. A manual can be a reference book, a user guide, or a series of small tutorials. Tutorials can be horizontal (a series of unrelated exercises) or vertical (a progressive series in which each exercise builds upon the result of the previous exercise). There are endless ways to provide information.
The point of this series of articles is to stress that documentation matters. For their investment in a CAD application, users want some form of guidance on how to use it, and that guidance is not always provided. There is no quick fix for this - time and money are required to produce good materials - but it is an investment well worth making. In today’s CAD market there are many firms offering what amounts to the same thing. Documentation can be what sets you above - or below - the competition.
About the Author
Bonnie Roskes, P.E. is a freelance writer specializing in technical documentation and training for CAD/CAM/CAE, structural design, mechanical design, and collaboration applications. Before making the switch to writing, she worked for several years as a structural engineer, designing and analyzing bridges. She now produces user guides, tutorials, online help, manuals, training material, e-learning content, and demos.
Recently she joined forces with other CAD writers to create F1, an outsourcing company providing software documentation and training for government contractors as well as CAD and engineering firms. Read more at www.f1help.biz.