Documentation Goes Electronic

Working with software, especially new software, has become a lot more challenging because documentation has gone electronic. Well actually thatd only part of the reason. The other problem is that companies are delivering less of the documentations stack than ever before.

Whats the documentation stack ? It is 3 manuals.

For new or significantly upgraded software at the top of the stack is a Getting Started manual of 10-50 pages which explains how to install the software and get started doing basic operations including step by step examples of the program in use. The Getting Started manual may also have a overview map or flow chart of the system, a glossary of terms, and 1-2 page where-to-go-next guide -> sort of like a FAQ on Help and/or How Do I ? For upgraded software, the Getting Started includes a Whats New and incorporates some of the new salient features in the step-by-step examples.

The second part of the documentation stack is a Reference Manual which descibes all the features, commands, and APIs enabled in the program. The reference manual is organized in alphabetical order with complete delineation of command/API syntax and options. A summary of the purpose of the command/function/API and as many examples of the code as is required to apply Pareto coverage – 60 to 80% of all practical usage will fall in these key examples. If there is a macro language, special resources, .INI (customizable start-up state info), or deployment mode of operations; those features are described in separate sections again in alpabetical order with Pareto coveraged examples. Reference Manuals can be as short as 10-20 pages but stretch into the hundreds depending on the program.

The third part of the documentation stack is a Users Guide which picks up from where the Getting Started Guide left off. the Users Guide explains the design principles used in create the program and how its creators envisioned it being used. It provides detailed examples including trade-offs, alternatives paths, gotchas and beware warnings. The Users Guide is critical be cause it explains and helps users get the most out of a program.

Whats Right About Current Documentation

Electronic documentation has improved quite dramatically with help systems. For example, in the graphics arena there are literally hundreds of command and menu operations for Adobe Photoshop, Corel Draw, ElectricRain Swift3D or Jasc PaintShop Pro. Lots to learn and remember how to use. So all the graphics vendors use wizards or coaching dialogs to get users through some of the tough functions/features. As well many vendors now make it easy to attach or park a hints bar or learning center as a permanent pane on the desktop.

These coaches or hints bars can be very effective for novice users. For example, as users change tools, so does the contents of the learning center/hints bar. Click on a hint and a step by step explanation of how to do an opeartions is available. Pro users can easily collapse/close the hints bar.

Some vendors like Adobe and Corel have a DoIt! option – click on the button and one of the steps is automatically done for you – sometimes including mouse clicks and other actions. So after seeing the program do it, novice users are more likely to pick up the sequence next time. As well, now error messages are embedded with hyperlinks to the help system or the hintbar – explaining the possible cuases of the error/exception more fully. Oor showing users where to find out how exactly to complete a particular operation.

Finally, more companies are including how-to demo animations and videos using software like Macromedia RoboDemo or Qarbon Viewlet Builder. Camtasia Studio takes this one step further and records videos (no missed steps or jerky mouse movements) of operations. Instead of tell me – these are direct “show me” electronic help aids. But as active help has gotten better, the baseline back up documentation has gotten worse.

Whats Wrong with Current Documentation

First, much of it has become electronic only. This is okay for a Reference Manual, where having hyperlinks to related commands, the ability to cut paste example code, add dynamic bookmarks, and search for terms and related concepts adds value for the lost convenience of being able to read anytime, anywhere and without any power requirements other than a bit of concentarion and focus.

But electronic Users Guides or Getting Started Manuals are too much. I dont want to have to take a portable to the John or on the RedRocket in order to catch up on some new methods in Flash. Oh wait, Macromedia Flash 2004 does not have a Users Guide. It has a an electronic Starting Mishmash Manual of sorts, and a printed ActionsScript 2 Reference Manual for $50US extra. All the rest of the documentation is scattered through for sale Macromedia Press books or somewhere on the Macomedia Developer Centre.

Ditto for Suns Java Studio Creator. The three separate manuals have been merged into one printed book, Java Studio Creator Field Guide which is neither fish but rather a foul ball way off the line. Ditto Infopath 2003 which has electronic documentation of some help – but then you have to go up to the Microsoft site or wait for the first two Sybex and/or Wrox books to cover the product to get the real, complete written documentation.

Ditto for Oracle 10g. Or one too many programs …

Users are now waiting 2-8 months after a program is delivered to get a complete set of documentation – and often that is out of date, subject to errors, and lacking in cogent examples. And frequently that documentation is being produced by third party writers not necessarily from the original ISV vendor. As the immediate problem solving electronic Help systems have gotten better, the initial learning and big picture written documentation has gotten scarcer, is less complete and costs extra.

Hmmmmm … when did I ask for this tradeoff ?