Working on Group Technical Writing Projects

After two months of graphical edits, I am finally nearing publication of the documents I have been hacking at since last October. At this point, all that is left is to make the documents as readable and attractive as is possible under the circumstances. The people on my team are examining each document — looking for grammar errors, spelling errors, and formatting errors.

We caught most of the errors during earlier edits, but the point of this pass is to ensure that the documents are ready for publication. The documents we are working on are not meant for the public, so they do not have to be flashy (and they aren’t) but they will be read by a key client who will be developing tools based on our product. That client must have documentation that works for them, and that means it needs to be clearly written and cleanly presented.

There are currently three of us working on the documents. Each of us lives and works in a different city. One person is a regular employee (which means she is in charge) and the other is a contractor who has some time to help get this document out. We communicate through e-mails and phone conversations. We track our project using an Excel spreadsheet that resides on out Documentum server.

Unfortunately, ours is not the only project tracked by this spreadsheet. More than once, I have spent valuable time fixing the damage done to the spreadsheet by the anonymous people who work on related projects. I cannot really blame the other people. Excel is a Microsoft product. With Microsoft, you must expect and even plan for errors.

Working with people across long distances is part of doing business these days. Both of my editing partners live in the United States, which is where I live, but I have also worked with SMEs across Asia. At other companies, I have worked with people in Germany, Ireland, Australia, Canada and Scandinavia. Sometimes the distance is smaller. This company has another division just ten miles away.

I only work with one other person who is also on site. There are four other people around who perform similar functions, but we have only a passing acquaintance. Most of the people near me are on a completely different project and work for a different business group.

One of the keys to working with people across distances, especially as a writer, is patience. In many cases, you will not get the answer you want when you want it, especially is you are separated from the other person by several time zones. The SMEs in Asia are just showing up to work as I am leaving, and I work late. You get used to asking a question and then moving on — finding other things to do until the issue is resolved.

In many cases, by the time the answer comes back, you have to check your notes just to remember what you were asking about in the first place. This can be a painful process if you do not keep good records of what you are doing. For this reason, I prefer email to voicemail. It is difficult to remember exactly what you said, but easier to bring up something you wrote. Whatever your method, always keep some sort of record of who you have requested things from, and exactly what you requested. It is also good to have a plan for how long you will wait before you ask again.

The main point to remember when working within a group that does not share a location is that the entire group is dealing with the same problems you are dealing with. While you are waiting for one person to answer a question, they are waiting on another person. Everyone is in the same boat, even if their part of the boat is in a different city or country. Sometimes you need to be proactive. You might need to set up a teleconference to hammer things out, even if it means staying three hours late or coming in three hours early. You might need to guess about an answer and come back to it later. Whatever the problem, you must find a way to do your job. That is why they pay you so much money.

How Technical Writers use Microsoft Visio

For the past two weeks, I have been fixing FrameMaker document graphics. Most of the documents I am working with are the same ones I mentioned in Boilerplate. The problem is that the graphics contained in those documents do not conform to company standards in multiple ways. In order to conform to company standards a FrameMaker graphic needs to be:

• 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.