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 to Design Technical Documents Visually

I am still up to my virtual armpits in graphics. For a month and a half I have been translating, transferring, resizing and redrawing graphics. While I have often designed graphics for different projects, the past few weeks have provided me with more intensive graphic application experience than I have ever had in my career. Unfortunately, one of the side effects of the great number of graphics to be worked on is that I don’t have the time to explore and understand the reasoning behind each graphic. This means that most of the fixes I can make only improve a few aspects of the visual language of the graphics. For those who don’t know, the basics of visual language are as follows:

Visual Arrangement

This is the order and organization of the visual elements within the graphic. The goal in technical documents is to arrange the information so that it is as helpful and informative to the reader as possible.

In most cases, I can only make small adjustments to the arrangement of these graphics. I might move a line of text to where it is more readable or separate two graphic elements by a wider margin so that the image does not look as crowded. Because I don’t have time to investigate the reasons behind the graphic, a complete rearrangement is out of the question. One influence I can have on arrangement is standardization. Often a graphic will contain similar shapes of slightly different sizes (usually the effect of drawing each item separately), and I will often standardize the sizes to give a greater uniformity to the arrangement.

Visual Clarity

Clarity means that the graphic is easy to understand and interpret. This means such detail choices as what words are used, and how an object is drawn. The information must be presented in a manner that is clear and understandable.

This is a part of the graphic I can make the most progress on. I can change fonts, redraw lines or shapes and generally sharpen the image so that it is easier to see and read. Often the SMEs (subject matter experts) who design the documents have low graphic application skills. I can make an image clearer just by adjusting line weight or redrawing the graphic so that the circles look like circles instead of rounded diamonds.

Visual Conciseness

Conciseness deals with the complexity of the image and the information presented. The goal is to present exactly the right amount of information. You do not want to give the reader information/clutter they won’t need or use, but you want to make sure every element that they do need is contained in the graphic.

I have very little say over this part of the process. Because I do not have time to interpret each drawing in detail, I cannot add or remove information at will. I have to trust that the SMEs know what it needed and what is not. Generally, I can only make adjustments to conciseness by adjusting emphasis.

Visual Emphasis

Some parts of a graphic will be more important than other parts, and a good visual designer will make sure that the most important aspects of the graphic are stressed. If the key purpose of a graphic is to show a linear progression of events, for example, that part of the graphic should be emphasized, perhaps giving less weight to individual events than to the line that connects them.

This is a part of the process I can make a guess about and influence, but often I have to live with the SME’s choices. I might choose to make one line weight greater than another, or individual text larger than other text but I cannot make major changes. As long as I do not eliminate or change information, I have some leeway here.

Visual Ethos

Ethos is, in essence, the credibility of a document or graphic. When a reader looks at a graphic they should be convinced that it is accurate, useful and important. Is the information correct? Can the reader use it to accomplish a task or interpret data? Does the graphic satisfy a relevant requirement? An important part of ethos is presentation. A well-drawn graphic will seem more credible than a poorly drawn graphic, even if both present the same information.

I have no say in whether the graphic is useful or accurate. I can correct spelling or grammar and improve the look of a graphic, but I do not have the time or information to decide if what is presented by the graphic is credible or useful. I must trust the SMEs (shudder).

Visual Tone

The tone of a graphic helps present the information. A tone may be serious, humorous, authoritative, persuasive, casual, formal or technical. For example, a technical image used in a sales or marketing presentation would generally be presented with a different tone than an image used for a technical manual. In that same sense, the images in a user’s manual for a video game would differ in tone from the images in a hardware reference manual or a technical proposal.

Tone is also something I have little say over in this case because I cannot redesign the graphics even if I must redraw them. However, because the documentation is highly technical and meant for engineers and programmers, it benefits from the fact that the SMEs are engineers and programmers. Their visual design skills are very straightforward and plain, which fits the general tone of the documentation.

As you may have noticed, these elements of visual design are interconnected. A change in conciseness or arrangement may influence clarity, a change in clarity or tone will influence ethos. Each element of visual design should be looked at separately as well as in the way it connects to other elements.

Visual design is an important skill for technical writers, and it is one that I am still working on (as anyone who visits my web site will attest to). I have taken a class in visual design for technical documentation and I have worked with and learned from graphic designers. I know how to use a variety of graphics programs such as Visio, Illustrator, Photoshop, and Paint Shop Pro. My skills are far below that of a graphic designer, but they are generally appropriate for a technical writer.

All technical writers should make some effort to learn visual design. I recommend that anyone interested in visual design start out with this simple and inexpensive book — The Non-Designer’s Design Book by Robin Williams. Once you feel comfortable with its contents, you might move on to the more in-depth (and expensive) Designing Visual Language by Kostelnick and Roberts.

How to Express Yourself Through Writing

Most people who write poetry or fiction do so because they want to express themselves. Self-expression takes many forms, but poetry and fiction are two of the purest forms. What you write will always be an expression of your inner self. Still, expression is not always a simple task. Anyone who has sat down to write knows how hard it is to find the words to say exactly what they want to say. What comes out is often close to a person’s feelings, but rarely seems to express them perfectly.

Below are the four barriers to self-expression that come up most frequently. If you want to write what you feel, you must learn to overcome them.

Poor Grammar Hurts Self Expression

Learning and practicing the basic rules of grammar and style is a key to self-expression. When you know and accept the rules of a language, those rules become tools instead of barriers. William Strunk’s excellent guide to grammar can be found free on the web at: http://www.bartleby.com/141/. This is an older, public domain version of the book The Elements of Style. This book is about as concise and inexpensive a guide to grammar as you can find. Buy it, read it, learn it, live it. There are many more guides, most of them more detailed and explanatory. I have at least a half a dozen different grammar guides, but as the occasional email points out, I still make mistakes.

Poor Vocabulary Hurts Self Expression

The second barrier to self-expression is vocabulary. I do not mean that you need to know hundreds of four-syllable words in order to express yourself, but knowing the right word to express your thought is an essential element of good writing. Most people think a thesaurus is a good way to build their vocabulary, but frequently a thesaurus can lead you down the wrong path. Just because two words have similar meanings does not mean they have identical meanings. It is far more important to read a dictionary than a thesaurus. Look up words, even words you think you know, and pay attention to the definitions. An excellent dictionary to buy is The American Heritage Dictionary. I am not a big fan of Webster’s Dictionaries; most of their definitions seem incomplete to me. The king of all English language dictionaries is the Oxford English Dictionary (OED). It is the most in-depth and comprehensive dictionary in the history of man. The OED is almost as expensive as it is extensive, so visit your local library if you cannot afford a copy.

A Lack of Honesty Hurts Self Expression

While the first two barriers to self-expression are technical, the third is psychological. Self-expression requires a level of honesty and fearlessness that most people do not possess. To begin with, you need to know what your feelings are. This requires taking the time to look at yourself and to try to understand why you do things. Once you know what your feelings are, you need to be brave enough to put them on paper. Some people never achieve that level of honesty. One way to work on breaking down barriers is to try automatic writing. Sit down with a notebook or your computer and write whatever comes to mind, as quickly as possible. Do not edit yourself and do not try to control what goes onto the paper. You can do this for increments of five to ten minutes or longer. Personally, I find that I don’t get a good automatic flow going until I’ve been at it for over fifteen minutes.

A Lack of Effort Hurts Self Expression

Writing well requires hard work. There is no easy way around this. The more frequently you write and edit, the better you will get at it. Most professionals spend hours a day writing. If your goal is to become adept at expressing yourself, especially through poetry or fiction, you need to understand that you won’t automatically be perfect at it. Even after years of practice, not everything you write will be worth reading. The key is to keep writing. When you have significant writing experience, you can plow though the dry times and take greater advantage of inspiration when it comes.

One of the most inspirational books I have ever read about writing is If You Want to Write by the late Brenda Ueland. When I read her book, it usually takes only a couple of paragraphs before I feel like writing again.

For More Information

• 5 Ways to Instantly Become a Better Writer
• 3 Easy Ways to Write with Style
• 7 Bad Writing Habits You Learned in School

Five Simple Ways to Help Market Your Writing

You must always market your services, even when you have all the assignments you need. Marketing during the good times keeps the slow times at bay. Here are a few very simple steps that many writers fail to take.

Purchase Business Cards
Some people believe this is too obvious to mention. However, I am always shocked by how many professional writers don’t have business cards. My advice is to use both sides of the card. The front side should contain the traditional information such as name, occupation and contact information. The back side should contain a mini-resume with a short list of your experience and services.

Create a Portfolio
You should create a promotional kit describing your services. The promotional kit should include a resume, samples of your work and letters of recommendation. Compile these in a nice folder. You might have very large samples (such as books) that don’t lend themselves to putting in a folder. If so, consider creating a samples CD. You will want to leave this with prospective clients or employers. Never give a client the only copy of your work.

Get Letters of Recommendation
As I mentioned, a portfolio should include letters of recommendation when possible. Don’t be afraid to call up former clients or employers to ask for a letter of recommendation. If they seem pressed for time, be willing to write the letter and have them sign it.

Make Business Contacts
While you’re calling all those people looking for recommendations, don’t forget to ask them if they have any business for you or if they know anyone who might be looking for services. Most employment is actually found through friends, acquaintances and old clients and employers. They are a much better source of information than job boards and newspaper classifieds.

Join Writers / Editors Groups
This is another part of networking. Meet other writers and editors. Establish a peer group. Some groups for you to consider are the National Writers Union (NWU), Society for Technical Communication (STC), American Society of Business Publication Editors (ASBPE), The American Society of Newspaper Editors (ASNE) and the The Public Relations Society of America (PRSA).