|
|
||
Using a Word Processor for Technical Documentation and Books© Copyright Darrell Anderson. Using a word processor for technical documentation and books is actually a straightforward process. There is no magic involved. However, read the opinions of some people and one is led to think that a word processor is useless for anything other than letters to Grandma. This is hardly the case. As of this writing I have been using word processors to provide technical documentation and books for more than 15 years. I never have experienced many of the so-called challenging issues described by many people. I started with WordPerfect 5.1 for DOS back in the late 80s. I migrated to Word 6 and then to Word 97. Hopefully sometime in the future I get my feet wet with OpenOffice or KWord. That is not to say that modern word processors are perfect because they are not. Nonetheless, through the past two decades, I have written hundreds if not thousands of technical procedures, guidelines, and How-Tos. I’ve written several books. I have developed procedure writing systems and an office document system. All with a word processor. Creating technical documentation and books with a word processor requires the following:
Much like Thomas Edison’s famous comment that “Genius is one per cent inspiration and ninety-nine per cent perspiration,” creating technical documentation and books with a word processor is largely one of attitude. Frankly, the many people who belittle word processors as adequate tools for these tasks suffer from an attitude problem. When I read such opinions usually I conclude from the article or essay that the author actually has little writing or publishing experience and is instead only interested in evangelizing. There are many word processors and text editors available, but only a high-end model supports these projects. Do not consider any product that fails to fully support templates and styles. Find such a tool and you provide a solid foundation for writing complicated documents. In the proprietary world, Word and WordPerfect are well known for providing such support. New on the horizon is OpenOffice, the open source office suite. Another product often used in the technical documentation and book writing effort is FrameMaker. Opinions and allegiance vary and I will not discuss which product to select. The important point is that a highly structured writing and publishing environment exists within these software tools. The next step is a willingness to use templates and styles. There really is no hope for any budding author to succeed in developing technical documentation or books without mastering these essentials of the trade. Creating valuable templates and styles does require focus and effort, but is well worth the time. I maintain several templates for my personal use and I am continually tweaking them through the years. The beauty of using templates and styles is that one creates a single-source control environment for modifying a document’s formatting. Instead of searching for all text that is bolded, one merely adjusts the underlying style and the entire documents is revised within a few moments. My observation is that few people are willing to discipline themselves to use templates and styles and that is a significant reason why many people scoff at using word processors for complicated documents. Important to the philosophy of using templates and styles is to avoid using free-lance formatting tools, such as the infamous bold, italics, and underline tools. Writing in this manner requires a lot of internal discipline. So accustomed have I become to working with templates and styles that in several of the templates I developed I purposely removed the bold, italics, and underline tool bar buttons and menu options. That then requires users to depend upon styles. Of course, the common question arises as what a user should do if no particular style exists to format text in a specific manner. That answer is easy—create a new style and add that new style to the template. The next step is not mandatory but useful and that is to learn how to write macros. All of my templates use macros and most are hand-written. The procedure writing systems I developed were entirely based upon templates, styles, and several dozens of underlying macros. The user, however, only saw tool bar and menu options to support the procedure writing environment. Macros allow users to automate numerous tasks and that reduces the time involved in maintaining complicated documents. A well designed macro does not look or feel like macro, however, but merely another point-and-click tool option. Lastly, most professionals involved in the technical writing field and probably all people involved in the book publishing industry, invest a lot of time in learning and mastering their word processor tools. This is the only practical way of moving past the point of writing little more than letters to Grandma. Consider that I wrote this document using a word processor and a template. That template includes a list of styles. With the help of another template and a tool set of macros in both templates, I converted that document into an HTML document, the one you currently are reading. Every document at this web site was created the same way. Notice that all of the underlying HTML code passes muster with respect to code validation. I accomplish that by paying attention to detail and mastering my tools, just as any skilled person would do. Writing technical documentation and books with a word processor is not difficult—unless you insist upon making the effort difficult or are more interested in evangelizing. Finis. |
||