• Published as a postscript file or (more frequently) a Microsoft Visio file.
• Given a standardized name / file number that appears in the bottom right corner of the graphic.
• Stored in Documentum in a special graphics archive.
• Pasted into an anchored frame within FrameMaker.

The SMEs (Subject Matter Experts) who created these files are expected to conform only to the first rule, and the documentation team is supposed to finish the job. Unfortunately, most of the SMEs are either unaware of the process or choose to ignore it (there is evidence of both on a case-by-case basis). This means that the graphics the SMEs put into the FrameMaker documents can come from anywhere. In practice, however, most improperly created graphics come from one of three applications, Microsoft Word (the most painful to transfer), Microsoft PowerPoint (bad, but not as bad as Word) and FrameMaker’s own drawing tool (least painful). My job is to go through each document, transfer any non-conforming files into Visio, fix the graphics problems, set the file name, save and store the base graphic files in the appropriate Documentum archive, then paste the revised graphic back into FrameMaker.

Visio is a surprisingly useful product, despite the fact that it is sold by Microsoft. The reason it is not as terrible as Word or PowerPoint is that this program did not originally come from Microsoft, but came instead from a company called . . . Visio. Microsoft bought Visio out in the year 2000, and as of this point Microsoft still has not managed to ruin the tool. Visio actually works.

Visio has some of the features of draw and paint programs, but it has a much different emphasis. Visio is used to quickly create flowcharts, graphs, charts, schematics and other technical or process-based images. Visio accomplishes this by providing the user with icons, charts, and line tools that can quickly be placed and connected on the page. Each icon is also set to allow the input of short descriptive text. The learning curve for this application is twofold. Not only does the user need to learn how to use the tools of the program, but they also need a firm grasp of the theories behind the creation technical images and how they are used to present information.

Of course, SMEs generally have very little training in either technical graphic creation or Visio. This means that many of the graphics accompanying these documents are in bad shape. The worst of the files are the ones created in Microsoft Word. If you have access to the original Word document that contains the graphics, you can make a painless transfer from Word to Visio. Unfortunately, if you do not have the original file (I usually do not) and have to rely on the image as it is pasted into FrameMaker, the transfer is so poor you will often find yourself redrawing the graphic from scratch.

The FrameMaker drawing tool, on the other hand, pastes into Visio with a minimum of fuss. The most common problem I encounter with it is that the text in the graphics will sometimes crowd together. When this happens, I can generally fix the problem by selecting the image and stretching it slightly. The ratios of the graphic elements stay the same, but the text gets the room it needs and the image looks the way it was meant to.

Many aspiring technical writers do not understand how important graphic and design skills are in technical writing. When people hear the term technical writing, the word writing has too great an influence on their thinking. The term technical communication is actually more accurate, but has little chance of becoming the widespread term for what we do. The truth is that charts, graphs, drawings and screen captures are often more useful that a well-written sentence when you are trying to instruct or inform a person. In most cases, the images will be the starting point for readers.

In addition to graphics, the visual design of a page can either help the reader or hinder them. When a document is poorly designed visually, it erodes the reader’s confidence in the material and hinders their ability to digest information quickly. Every aspiring technical writer should take a visual design class.

Here are two valuable books on the subject of visual design:

Robin Williams. The Non-Designer’s Design Book. isbn 1-56609-159-4. Amazon

This book is an excellent introduction to the ideas behind effective visual design. It is not particularly long or detailed. It simply shows and tells you why certain ideas work better when designing anything from a business card to a brochure to a manual. I have never seen a more straightforward presentation of visual design.

Charles Kosterlnick & David D. Roberts. Designing Visual Language: Strategies for Professional Communicators. isbn 0-205-20022-2. Amazon

This is a formal textbook on visual design with an emphasis on technical communication. It discusses both high-level concepts and low-level details. This book is far from quick read, but if you stick with it, you will gain an excellent knowledge of visual design from a technical communicator’s standpoint.

Adobe FrameMaker is the industry standard for writing book-length technical documentation. It is a powerful program capable of creating books of well over a thousand pages. The learning curve for the program is significant. Adobe FrameMaker is a much different animal than Microsoft Word and other word processors.

It uses, not surprisingly, a frame system (pre-designed pages that text flows into) for creating pages. The user designs frames to apply to pages. Each frame can contain a combination of text and graphics. Those frames either operate as separate and distinct units or flow from page to page. Using these frames, the user sets up master pages and reference pages. These pages allow the user to create a standardized, but still very malleable, series of pages. The user can design a page to implement at the beginning of a chapter, for example, or design a page specifically for tables, graphs, or other graphics. Creating templates can be tedious, but once they are operational and you know the shortcuts, you can develop documents quickly.

Adobe FrameMaker versus Microsoft Word

In addition to the frames, another feature that separates Adobe FrameMaker from Word is its ability to create character formats, paragraph formats and implement variables. Microsoft Word has these capabilities, but they are much more limited than Adobe FrameMaker’s. More importantly, few Microsoft users have ever bothered to explore these higher functions and they remain quite buggy.

Adobe FrameMaker’s greatest feature is its bookmaker. The bookmaker allows you to develop different files around different functions. For example, you can have a file for the cover, for the front matter, for the table of contents, for each chapter, for the appendices, for the glossary and for the index. The bookmaker then keeps track of all these documents and makes sure they cooperate for such tasks as updating the table of contents and the index.

In my situation, the form of the pages was long ago set. I do not have to develop pages or frames from scratch. Unfortunately, many of the documents I will work with were written in the 1990s using Adobe FrameMaker 4. The current version of Adobe FrameMaker is 9, and many changes have occurred in the interface and the document handling. Because of that, I must subtly massage the documents to bring them into line with current standards. For example, there are some invalid fonts and minor formatting flaws that I have to look out for.

Additional Resources

• Adobe FrameMaker 9 Classroom in a Book
• Adventures with the New Technical Communication Suite from Adobe
• What’s new in FrameMaker 9

My face-to-face interview with the company was similar to my phone interview. So similar, in fact that more than once I found myself answering the same questions I had answered over the phone. They did throw a couple curve balls at me, however. The strangest question I was asked was, “If we called your references, what would they say about you?” I was unprepared for this one, and I ended up talking more about my references than about what they would say about me.

My basic statement, however, was one that I have used before. “Once I take on a project, I am very committed to it. I will fight for a project, often to the consternation of those around me.” This isn’t the most positive thing I can say about myself, but I don’t like to walk into an interview and give people a false impression either. I discussed how I handle situations. I told them I’ve camped in people’s cubicles to make them give me the information I need and I’ve gone to managers when I felt people weren’t cooperating. I told them that if they are looking for someone who is always tactful and compliant, I may not be right for their project.

Apparently they weren’t too scared off by my answers. They gave me two “take-home” tests (I could have done them there) to prove I knew what I was doing. The first was a general test of FrameMaker skills, and the second was an editing test. I found both tests to be pretty easy and I emailed the tests back the next morning. Less than an hour after I sent them the tests, I got a call telling me I was hired.

Technical Writing Contract Negotiation

I had already agreed on a rate for this job ($25 an hour) and so I was surprised when my recruiter called and said she wasn’t able to get me that rate. Just as I was about to panic, she revealed that they were actually going to pay me $30 an hour. Why did they raise it? I haven’t a clue. They had me at $25.

There were some contract negotiations, however. Most of the contract was fine except for clause 14:

Failure of the employee to report for work at the date, time and location above specified shall constitute a breach of this contract and the employee shall be SUBJECT TO LIQUIDATED DAMAGES IN THE SUM OF $5,000.00, payable to ____.

The clause is not as unreasonable as it seems at first. Once a consulting company commits to a contract, they assume a financial responsibility for that person showing up to work but there was no way I would agree to the contract unless the clause itself referred to a specific date and time when I was to show up. I “discussed” this with them over a series of phone calls that went all the way to the president of the consulting company and I finally got my way.

After that was settled, I signed the contract, a non-disclosure form, a criminal background check release, and direct deposit forms. Because the consulting firm is in Dallas, All of this had to be done long distance. There’s a good chance I will never meet my recruiter or account manager in person. This did create a problem at one point, when one of my faxed contract pages went missing and I had to go through my papers and fax the page again.