The State of Documentation, Part 2
By Bonnie Roskes, P.E., October 15, 2002
This is the second 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.
Part 1 of this series presented reasons not to skimp when producing software documentation. Good documentation is an investment in user confidence and satisfaction, and can save as much as (or more than) it costs. While there are probably very few in the industry who would dispute this, documentation remains inadequate for many applications. This article analyzes some of the reasons behind this fact.
Why Are the Manuals So Bad?
Like users of all software, CAD users want better manuals and training materials. Industry experts and software company managers bemoan the lack of quality documentation, and agree that more should be done. But documentation continues to be given short shrift. There are several reasons why this is the case.
MONEY During budget allocation at a software firm, the first handout goes to R&D, so that a functional and bug-free product will be released on time, and so that good application engineers and programmers can be (deservedly) courted and compensated. Sales and marketing are next; they need funds to give proper attention to advertising, industry press, trade shows, and exhibitions. As for documentation - it's rarely given a high budgetary priority, and the slight is clearly felt by the user.
If a firm is lucky enough to have an in-house tech writing team, budget constraints usually limit the team with insufficient or unqualified employees. To stretch their personnel dollar, firms will hire novice tech writers, or writers with no knowledge of CAD. A writer who doesn’t understand wirefames, surfaces, and solids has a hard time explaining these concepts to others. (Though to be fair, most tech writers are not technical people; many were journalism or English majors, and write for CAD as they would any other genre of software.) So the writers make do, providing whatever documentation they can with their limited resources.
In most cases, a barebones budget will yield a skimpy training manual that covers only a bare minimum of concepts and tools, and online help that is incomplete or incomprehensible.
TIME A large portion of the manuals, online help, and tutorials cannot be completed until the software is locked and hermetically sealed. Even slight changes can necessitate replacing screen captures, revising tutorial steps, or changing reference material. Although writers are usually promised that software development will be finalized several weeks before the release, allowing documentation to catch up, in reality this almost never happens. Last-minute bug fixes and changes are hard to predict, and, understandably, the software almost always morphs until the last possible moment. This leaves the harried writer with very limited time to write new content and update existing material before the release deadline. And if a release is held up by documentation, the writers are often blamed, regardless of who else missed deadlines.
From a logistical standpoint, then, the typical software development process is not conducive to creating adequate documentation. One simple remedy is to release downloadable manual updates and new tutorials after the release, but this can be messy. Companies (rightly) like to offer everything related to a release in one neat package, and users (also rightly) don’t like to be bothered with downloads and updates. So unless development-locking deadlines are taken seriously, or releases are reasonably postponed, this problem will likely persist.
Shipping Costs CD’s are incredibly cheap to produce and are also cheap to ship, even when accompanied by some literature such as a registration card or small installation guide. Downloadable software eliminates shipping altogether. So when a printed manual is produced, it is by far the most costly component to ship. Printed material also requires storage space before shipping, which not all firms can provide on-site.
To eliminate the shipping problem, a book can be converted to HTML or PDF and made available on a website. Files that are too large to download can be placed on a disk, or they can be broken down into chapters. Portable books provide the added advantage of allowing the user to print only sections that are needed, and provide the option of onscreen viewing. However, not too many people want to do their own printing; all those individual 8 ½ x 11 sheets can get messy and you will invariably run out of toner while printing out a 200-page manual.
Most users want to receive a nice bound book that fits on their shelf, and some prefer keeping everything on their computers. Those who want the book would probably be willing to pay a few dollars more to cover the shipping, and the decision to take a printed or online manual could become part of the overall software purchase.
Independent Authors Do a search for books on Autodesk products alone, and you will find hundreds of titles. Independent books are available for most of the major CAD applications, covering every possible usage scenario, and covering a wide range of prices. Many companies may feel that it’s a waste of resources to produce in-house documentation when someone will surely come along and write about it. (I am personally thankful for this attitude, otherwise writers like me wouldn’t have so many opportunities to write and publish books!) However, when users need to open their wallets for a “How-To” book - after already shelling out plenty for a pricey application - it can leave a bad taste in the mouth.
Even the best documentation will not eliminate the need for independent books; people will always want books on specific topics or by specific authors. But it doesn’t reflect well on the software itself when these books are the only decent source of information.
Training Income Large software companies and VAR’s make good money from instructor-led training courses. This may be cynical on my part, but sometimes I can't help wondering whether there is a fear that providing quality help and training with the software would reduce or eliminate the need for these courses. I don’t think this is truly the case, however. Even with the best manuals or self-paced tutorials, some people still prefer live, instructor-led training. And since no documentation can cover in detail every aspect of any software, courses will always be needed for more advanced and specialized topics.
Mindset Highly technical people, such as those who produce software, can usually figure out how to work anything without reading the instructions first. But not all CAD users are so lucky. While most application engineers and programmers think their software is self-explanatory and their user interface sufficiently transparent, their users may have a different perspective. It’s not easy for R&D to put themselves in the shoes of their typical user, especially after becoming so intimately familiar with the software they’ve created.
Battling this mindset can be a tough job for tech writers. Not all those who use CAD understand all the concepts behind CAD, and many need extra guidance on topics the engineers and programmers find elementary.
Notable exceptions to these unfortunate “rules” do exist. Many firms devote funds and hire or outsource good writers to develop good manuals and training. But more often than not the attitude is “yes, we really need to beef up our manuals and produce a few tutorials, but we just can’t do it right now.”
For all the obstacles I’ve outlined, solutions can be found when documentation is taken seriously. For most users, a slight delay in release or the need to download a few files is worth it to receive quality materials that will help them understand and use the software they've just bought.
In the next article, I will analyze the usefulness of various types of documentation - manuals, online help, tutorials, demos, and training courses.
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.