At most companies today, a technical writer also acts as a technical editor. Back in the day (the mid-80s, which I hear about a lot in the software industry) technical writers were only expected to write. Technical writing departments often had their own editors and illustrators or graphic designers.
That is almost never the case anymore. Desktop publishing has given writers all the tools they need to produce a document. Graphics programs (for example, Adobe Photoshop or InDesign) are so prevalent that a tech writer is expected to be her own graphic designer. And most technical editors are probably now technical writers or educators.
For example, in my last job there were about 200 technical writers for a company of approximately 16,000 employees. There were about 4 or 5 technical editors who were also educators and trainers. They didn’t have much time to edit. When I left the company these technical editors had been absorbed into the technical writing organization proper, and no longer did any editing.
Editing is arguably the most important part of any writing project, fiction or non. I’ve broken editing down into four sub-categories:
Narrative fiction and technical writing both need a consistent, meaningful structure. Structure is borne of logic.
In tech writing you need to know your structure before you start writing. Structure is dependant on your main intended audience (the user), the “story” you are telling (how users accomplish a task), and the level and order of the information needed to tell a complete story. Often, after you’ve planned and researched a subject, you use an outline and/or table of contents to figure out the structure. Remember I talked about two ways to tell the story of a user’s guide: From easiest to most difficult or from start to finish. This story helps dictates your structure. It can change as you go (the configuration chapter should go after the installation chapter—who knew?), but your research and planning takes care of most structure questions beforehand.
Narrative fiction is a different animal. You might be saying (if you haven’t attempted a novel), well damn Unreliable Narrator; the structure of a novel is however you write your story. Structure? Follow your muse.
Following your muse alone might work for a couple of months or years. You finish a couple drafts, fix your typos, dot your i’s, cross those t’s, and then you send it out to a bunch of agents and forget about it for a while. Why? because you are done! Congratulations. In the following months you receive (if you’re lucky) a slew of rejections. Form letters or emails saying Not right for us or Not accepting new clients at this time. Fancy letterheads lose their impact when nobody signs the letter. Maybe you get one or two handwritten notes (but probably not) saying thanks but no thanks. What the hell went wrong? With all those novels getting published every week, where’s the love for your opus?
Chances are you’ve got some problems with your novel’s structure. Structure problems can be tough to spot. You need other eyes reading your manuscript. It doesn’t matter how closely you adhere to an outline or an overarching vision—your novel must strike a delicate balance, reflected in its structure. A novel’s structure can mean things like how to present multiple characters. Or when to reveal important information. Or weaving in a character’s back story or other important events that happened ten years earlier, but somehow affect all the characters now.
For example, say you decide to tell your story from the points of view of four characters, and you give each chapter over to a character’s third person view. The problem is, not all these characters are main characters. Two of them are main characters, and the other two, not so much. So, you can’t give the minor characters equal time, you have to strike that perfect balance, giving the main characters more air time or else the reader will wonder who the story is about, who they should root for and empathize with. But, you already wrote the book, and sent it out, before one of your readers pointed this out to you.
Structure problems for both tech writing and for narrative fiction can be fixed. For tech writing it’s usually a matter of cut and paste. Or adding and subtracting. Sometimes it works the same way for narrative fiction. But novels are much more delicate. Pasting a paragraph from chapter 2 into chapter 10 will probably have repercussions, ripple effects. But don’t be afraid to tear up your structure and rebuild it. It might take some time, another draft or two, but if it makes a better novel, you have to consider invasive surgery.
This is closely related to structure, especially for narrative fiction. In tech writing the structure, story, and the main audience of the document dictates the pacing. You don’t want a user/reader to fall asleep reading your guide/online help, but you also have to give all pertinent information. Pacing for tech writing involves being concise and striking the right balance of information.
Writing concisely is tech writing 101. Don’t use ten words if you can use four. On the other hand, don’t leave out conjunctions just to save space. Just the facts. But not too many. Again, much of this is dictated by your audience. Are they new users that need more context and overview information? Then you’ll have to include an overview chapter with concept material. That’s tough reading, a slog if you will, so you want to write clean and tell your story with just the right words. Also, your company or your documentation group will have standards in place to follow. You don’t have to reinvent the user guide every time you write one. Good pacing in a tech document strikes a balance between giving the user the information she needs and keeping her from slamming the book closed in disgust because you gave her either information overload or not enough information.
Pacing in narrative fiction is closely related to structure. Let’s go back to my example: four characters spread throughout all your chapters. You don’t want to give one of the more minor characters the same number of chapters as the main character because this throws off the pacing. The reader might slog through minor-character chapters just to get back to a main character chapter. Give the main characters three chapters (for example) to every minor characters’ one chapter.
Pacing also comes into play at the beginnings and endings of novels. Where does your story begin? On page 1, hopefully. Maybe. Sometimes not. Sometimes your story doesn’t start until page 40, when your main character first steps into the crack house. So what about the first 39 pages? Read them again. You were finding your character, and anything important can be woven into the story after page 40; which is now your new page 1.
So your hero kicks drugs, joins the local police force, and eventually goes back to that crack house with his squad to bust the nefarious drug dealer. Ah man, great scene, full of action and pathos and irony and it’s obvious you’ve done your research. And the story is about to end, right? Wrong. You drag it out for another 75 pages. And the reader is stuck wondering what they’re reading. Did you introduce a love interest on page 350? Is she a new main character? How about the cop’s best buddy, a retired cop who’s now hanging around the station giving sage advice. Don’t end your book too many times. Know when to get out. Give the reader what you’ve set up in the first 90 thousand pages, and don’t give them another 15 to gnaw on. As with tech writing, you don’t want to give your reader unnecessary information that clouds the story.
In your novel, if a main character drives a Prius on page 3, he better drive a Prius on page 303, unless he sold it and bought a Humvee. If your main character is the type of guy who seethes with anger because he hates his job, then by the end of the novel he better have:
• Quit the job to follow his bliss
• Shot his co-workers because they were making his life a living hell
• Met and married a woman who showed him how great love and life is, making his day-today job more bearable
• Get very close to one or all of the above, but in the end doesn’t change
If you don’t follow through with all the emotions and situations you introduce, then you’ve got a consistency problem. If you think no reader noticed that offhand reference to bestiality in chapter two (you thought it would give your antagonist shading), you’re dead wrong. Readers notice the smallest details, even if they don’t know they’ve read them. After they finish the book and say, “Hey, not a bad little literary novel,” three or four weeks later they’ll start remembering odd bits and pieces that don't fit, including how you never followed through on that bestiality thing. It can be even more amorphous than that: they know something is wrong with the story but can’t explain what. Readers know a bad piece of writing, even if they can’t tell you why.
The same goes for technical writing, except in a more crucial way. Everything about a technical document must be consistent. Everything from the terminology you use to the minutia of spelling and structure. You must present a feature or concept the same all the way through. And not just in one document, but throughout a company’s literature. From online help, to a user guide, main corporate website, and marketing material. This can be a huge, odious, and time consuming job. And terminology is constantly changing as products continue to be modified and integrated. Consistency is really the heart of technical writing.
One of the most important jobs of a technical writer is to set the user at ease. Introduce the conventions of the guide in the preface, introduction, or first chapter, so that as the reader moves through the document, she knows what to expect. Unlike narrative fiction where a writer can turn all lyrical and subjective, or screw around with time or point of view, a technical document must lead the user through the logical progression of tasks with tact, clarity, and consistency.
If you use the term failover a certain way in chapter one, you must use it the same way throughout not just this guide, but in the online help, and in the marketing material. And you better describe failover the way it actually acts in the product: Your documentation must mimic what the user sees when she uses the product. Consistency is in the details. Cross references to other material (“See page 12 for more information.”) better be accurate, or users will get frustrated and stop turning to page 12 for more information.
Consistency must be maintained at all levels, even those a user may not even notice. But, like with a novel, they will be able to tell that something is not right. Even if they can’t put their finger on it. If you start the first procedure with an introductory sentence, then start all procedures with an introductory sentence. If you don’t, the user will wonder where the damn introductory sentence is, and say, “Maybe this procedure is in some way different from that other procedure; maybe it’s not as important. That’s it! I don’t have to follow this procedure because there is no introductory sentence.”
When you first tell a user to click Tools > Insert > Table, you are introducing a couple of conventions. What are they? Can you spot them? Bold. Whenever a user needs to click a button or other item on a user interface (like the one in which you are reading this blog) then it should be presented in bold text. What else? The > between items to click. This means the user is to click these items as a series of steps to insert a table. I used as few words as possible and I have the user trained for the rest of the user’s guide.
If you screw this up, the user will lose confidence in the guide. Will be more likely to contact technical support rather than touch another technical document from your company. Ever. Ever again. You’ve lost them. Forever. Introduce conventions and standards and use them consistently.
Noticing consistency in my technical documentation has helped me appreciate and discover it in my narrative fiction. Most of the editing techniques I’ve picked up on the job have come in handy when planning, executing, and editing my novels, stories, and outlines.
Predefined standards give a technical document much of its consistency. By standards I mean a set of rules you follow to give a company’s technical documentation a similar look and feel. It includes things like font type, how to format a numbered list, and putting a preface and index in every document.
Fiction writers define their own standards. They might pick them up from an aesthetic they learned in school. Or from certain writers that they read and emulate. Standards in narrative fiction have less to do with typeface and kerning than with how to use the rules of grammar, and breaking them or incorporating them when the story calls for it. Do you place a character tag before or after a line of dialog? Do you place description in the same paragraph as a line of dialogue or in a separate paragraph?
For my novel, "A Little Disappeared," I set a standard over the first two chapters for the reader to follow. The first chapter introduces my main character, Keith. Keith is 38 and his wife has left him. He has embarked on a cross country trek to find her. This storyline takes place in a contemporary setting and is told from the first person. Chapter 2 introduces the same character when he is 14 and is told in third person point of view. I follow this standard throughout the novel. If I’ve done my job correctly, the reader should be able to read the story and accept, or at least understand, this structure as a standard I’ve introduced early on. (Hopefully they’ll accept it, because it’s harder and much more expensive to get in touch with narrative fiction support than technical support.)
Whether you’re a tech writer or a novelist, you train your readers (usually in the first chapter) how to read your writing, creating a trust. If you break this trust with inconsistencies, then readers will be wary on some level of the story you are telling them.
These are just a few examples of where technical and fiction editing crossover. I tried to cover the most important ones. If you can think of others, let me know.
Tune in next time for the 4th and final post in this series when I’ll discuss:
- Technical reviews
- Peer editing
- Technical writing in fiction and non-fiction
- Is Technical Writing For You (or, do fiction writers make good technical writers)?