Wearer of Many Hatsby Carol Peterson |
My job title is "Technical Writer" and, in general terms, I work in the computer industry. But the details of my job go beyond writing, and the market my company serves is one I never even knew existed before beginning my job search.
I work for a company that publishes databases on CD-ROM. We take databases, primarily of bibliographic information, and put them on compact disc. We also write retrieval software that people use to search for information on the discs. Our product provides an alternative to online services like Dialog and Nexus, and our primary customers are libraries.
Because our documentation department is small -- three people -- and because we work on such a variety of documentation, we aren't locked into narrow job descriptions. At various times I am a writer, editor, graphic designer, software designer, and software tester.
In my role as writer/editor, I and my colleagues write, edit, and revise quick reference cards and user guides for each of our 70+ database products, as well as the installation guides and user manuals for the four versions of our retrieval software. We also create diskette-based tutorials and online help systems for our products.
Since our department has control over the appearance of all documentation, we design all our own styles and templates. This includes everything from selecting fonts to deciding on layout, page size, and format. I feel lucky to have this freedom from the constraints enforced at larger companies, yet at the same time it means we take responsibility not only for ensuring consistency among pieces, but also for choosing useable formats.
I am also fortunate because my company recognizes that documentation specialists should be involved in the software development process. Our input is solicited and welcomed during both the design and testing phases of software development.
One of our greatest challenges is audience analysis. We don't have the opportunity for direct contact with our audience, which means we are often designing documents based on our best guesses as to the users' needs. And we actually have two audiences -- librarians, who are experienced database searchers, and library patrons, who are novices. Fortunately, we have some ex-librarians on our staff who can act as reality checks for us. We are also interested in establishing some type of usability testing and are currently exploring ways of implementing this.
We currently use a variety of software and hardware tools to do our work. Unfortunately, there isn't one perfect software package that does everything we need.
All of our paper documentation is done in PageMaker (Aldus Corp.) on Macintoshes with two-page monitors. PageMaker has good text-handling abilities, including a sophisticated indexing function. Its graphical interface also makes it easy to lay out text. However, PageMaker also has some annoying drawbacks, such as its inability to keep track of cross-references and its rudimentary graphics tools. We are researching other publishing packages, but it seems impossible to get all the features we want in one package.
To support PageMaker, we also use a number of other software packages, such as SuperPaint (graphics -- Silicon Beach), ScreenShot (a screen capture program -- Preferred Publishers), and Word (word processing - Microsoft) on the Macintosh, and HotShot (another screen capture program -- Symsoft) on the PC.
For our online documentation we use a variety of products, depending on the requirements of the project. Our DOS product's help files are written in a text-editor (QEdit -- SemWare) and saved as ASCII text.
The help files for our new Windows product are being written in Microsoft Word (both Macintosh and Windows versions) because the Windows Help system requires files saved as RTF (Rich Text Format) text.
We also use Microsoft Excel to keep a database of the links in our Windows-based help system (Windows Help is a hypertext application). And to create our diskette-based tutorials, we use Dan Bricklin's Demo II (Sage Software), an authoring and demoing program.
Although it can be interesting and even fun to learn all these different programs, it can also be frustrating and time-consuming, especially with DOS-based programs as they are seldom consistent. For example, in one program the ESC key brings up a menu, while in another it exits the program. Trying to keep all these commands straight can be difficult.
A second annoyance is that the programs aren't compatible with each other. I have spent hours, and sometimes even days, trying to do something which should be easy, such as taking a screen shot with a screen capture program and placing it into a graphics program for editing.
Another challenge facing our department now is a result of both the variety of documents we produce and the growth of the company. Informal tracking methods are no longer enough. How do we maintain and update all our documents? How do we manage version control? How do we ensure quality and consistency? We are currently developing ways to manage these issues within our personnel, budget, and time constraints.
To ensure quality and consistency, we have established a standard checklist for all documents that includes items such as spelling and grammar checks, style and format checks, and tests of procedures and steps. We have also created PageMaker templates for most of our document formats and written an in-house style guide with specific style and format guidelines.
To keep track of revisions, we use an incrementing part number for each publication that includes information not only about the version number, but also about the type of document, such as quick reference card or manual. We also keep a file of required corrections that we are constantly adding to and which we check before reprinting any document.
In all, we have been fairly successful at managing a large variety and volume of work without sacrificing quality. Probably the biggest temptation we've had to resist is the seduction of high tech. It's easy to be swayed by the slick advertising of every new product; the trick is choosing only those tools that will actually enhance your productivity.