By Robert Delwood
Documentation teams traditionally have not written software or developed customized software tools. Many companies may consider those skills too specialized to relegate to writing groups, too costly, or do not see the advantages of automation. Many teams themselves just have never thought about programming, thinking such an effort may be out of scope or that the team does not have the proper skills. However, in this age of automation and convenient data access, there are significant gains to be made (such as better, cheaper, or faster in any sense of those words) by automation in support of documentation. To help you into this frontier, I’ve got a few suggestions based on my documentation management experience along with the experience from peers.
In the broadest sense, automation is the programmatic collecting, formatting, or checking of data. It aims to reduce the manual effort or replace repetitive tasks with predictable and repeatable applications or scripts. Automation can take many forms along a continuum, from the simplistic use of the Microsoft Word’s F4 key to repeat the last command to the full development of a conventional software application. In practice, documentation automation tends to fall more on the simple end of that continuum. The development effort ranges widely too. You can pick the level of involvement that is right for your team. Certainly, groups with formal programming experience (such as those with programmer-writers) have an advantage but not a lock. Reliance on simple methods of automation such as macros, for instance, still has benefits. For example, procedures that are thought to be one-time events, rarely are. If you perform a similar task twice, consider automating it or storing it as a macro (which stores all the keyboard, mouse, and other input actions as a single keystroke).
Automation is not about the writing process itself but rather it supports the process by getting or manipulating the information for you. The point is to get away from performing tasks manually. There are as many applications of automation as there are technical communicators and problems they have to overcome. As an example, assume a substantial amount of information is kept in your company’s database. In this case, say it’s a long list of your product’s error messages that need to be included in your help file. There are four gains automation could provide.
For as popular as Word and Visual Basic are, they are by no means the only applications supporting automation. Most applications (including those from Macromedia, Adobe, and Microsoft) include an API (application programming interface), which is the set of functions that can be accessed programmatically. In turn, the applications often support others’ APIs.
Although the thought of programming may seem out of scope and experience for writing groups, most teams can benefit from some level of automation, if the project is planned appropriately. The surest way to fail here is to overestimate your capabilities and over-promise your results. In short, keep the projects as simple as necessary to get one task done. When planning these projects, keep the following issues in mind.
The scope of the solution is to address one and only one problem. Whether it’s getting information from a database, checking the styles within a Word document, or generating pages in HTML, limit the scope. Don’t combine solutions until you’re more comfortable with automation concepts and implementation.
You’re writing scripts for a one-time, specific purpose and scope. Therefore, you don’t need extensive error checking or online help. A common time sink is trying to make the tool bulletproof. The audience may be equally limited, such as one specific writer or editor. In that case, you can specify exactly how to run the code or what parameters to enforce. Again, the point is to get a specific task done.
Because the tool is designed to do one specific task, it may have a short lifespan. That’s alright. Besides, good and useful tools will evolve over time.
For each new solution create a new tool. Don’t keep adding on to the same tool. This will only make it unusable for any purpose. Certainly base the new tool on an existing one that does a similar task but always start from a copy and modify it. Over time you will end up with a large collection of tools, applications, and scripts. But think of this collection not as a tool library but as an example library. Reuse portions of the code for other projects. For example, code that opens different files in a single directory or writes to an external file will likely be needed at other times. You will get speed and proficiency gains over time from familiarity with the code.
Identifying your unique needs and similarities among your processes expertly locates the areas to concentrate on. Since the project will be under the writing manager’s direction and approval, it is often easier, quicker, and more efficient than by soliciting outside assistance.
Visual Basic and VBA capabilities access virtually any aspect of a document, Word or otherwise. You may not use all the capabilities at first, but knowing what is possible will encourage you to push your solutions.
When you want to hang a picture, a hammer is not a solution, a nail in the wall
is. The same thing applies to automation. You will not be judged by the quality
or the elegance of the tool; chances are, they may not even know about them.
Rather, you will be judged on the document’s conformity to requirements.
In other words, automation is a means to an end, not the end itself.