The last of a 4-part series.
Technical Review
After a technical document has been written—or changed significantly from an earlier version—it needs to be reviewed for technical accuracy by a subject matter expert. A tech writer needs to learn all she can about the feature she is writing about (be it the integration of disaster recovery software or a new part of the user interface), but to ensure accuracy, she must often rely on the people who designed, engineered, and tested the feature. So, before a tech writer can say a guide or help topic is done, it needs to be reviewed from a technical perspective. More than once, if there's time.
If you are writing a novel that has many medical or scientific facts and concepts, and this is not an area of expertise for you, then you probably want somebody who knows more than you do to read your manuscript. Even if you interviewed a subject matter export and maybe even visited her at work to see what it’s like to be an emergency room doctor, getting the expert to do a technical review of your book is necessary to ensure you get the details right. Get more than one expert to read it if you can. That way you get different points of view, different feedback, and different ideas.
Peer Edits
Peer editing is a term we use in the tech writing biz. When you finish a draft of a guide, you want another writer to check it for consistency, logic, structure, and corporate standards, and to give a good proof reading. Getting a peer edit on your documentation is not just a good idea but is necessary to ensure you’re not distributing sloppy, confusing material. Sometimes you don’t have the time to get another tech writer to review a guide, and you just have to be your own peer editor.
There’s no time to let a draft of a user’s guide breathe. You can't let it sit in a drawer for a few months to come back to with fresh eyes. You finish the guide as much as you can and move on to the next. But technical documentation is a living document. Meaning, you’ll get another chance to make it better when you update it for the next release. How many times do you get to rewrite a story or novel after it’s published? Following pre-determined corporate writing standards and conventions help get it right the first time.
I enjoy reading other writers’ work and try to give an honest, helpful appraisal of the writing. Peer editing has helped me when it comes to editing my narrative fiction, training me to focus on problem areas and to be more objective.
Technical writing in fiction and non-fiction
As I mentioned, you might include information in your novel or story that must be technically accurate. This includes doctor, police, and lawyer stuff. If you include this stuff, make sure you’re a doctor, policeman, or a lawyer. Or you’ve interviewed one or had one review your story for accuracy. Or you've lived with one or are married to one (this is research—take advantage of it). Because if you haven’t done any research, your lack of knowledge will be noticeable on some level, especially to people in the field you’re writing about.
If you’re not writing fiction but another type of book, say a how-to like a cook book or craft book, then you are getting much closer to writing a technical document. You should be using more technical writing elements. These basic elements include:
- Numbered and bulleted lists
- Tables
- Hierarchical headings
- Cross references
- Chunked information
- White Space
- Indexes, glossaries, and tables of contents
These are all important and all help a user find information. My favorite is the list.
Don’t be afraid of the list. The mighty list is your friend. Read through your book. Every time you give the reader a task to perform, put it in a list. This list must start with 1. 1 Open the book. 2 Read every chapter. 3 Break nested tasks and sentences of items into lists. A task shouldn’t be too many steps. If it’s longer than 10 steps, break the task into two or three smaller tasks. Another type of list has bullet points rather than numbers. A bulleted list is a good way to organize stuff. It’s easy to read and helps to break up the monotony of a paragraph of text.
Here’s a rewrite of the last paragraph, using tech writing elements:
How to Use Lists
Don’t be afraid of the list. The list is your friend.
Guidelines:
- Read through your book. Every time you give the reader a task to perform, put it in a list.
- This list must start with 1.
1. Open the book.
2. Read every chapter.
3. Break nested tasks and sentences of items into lists.
Tasks
A task shouldn’t be too many steps. If it’s longer than 10 steps, break the task into two or three smaller tasks.
Bullet points
Another type of list has bullet points rather than numbers. A bulleted list:
• Is a good way to organize stuff
• Is easy to read
• Helps to break up the monotony of a paragraph of text
The idea is to break the information into chunks to facilitate easier reading and to help the reader find the information she needs quickly. Using the above rewrite as an example, say the reader is interested in learning about bullet points, and not tasks and numbered steps. Then, she can skip to the sub-heading Bullet points after finding the main section of How to Use Lists.
Is Technical Writing For You (or, do fiction writers make good technical writers)?
The early 00s was not a good time to be undereducated. Jobs were scarce, even in the Massachusetts high tech industry. I had a film making background, and had spent all of the 1990s working in the wedding video and video duplication business, while also writing short stories and novels. By the end of the 90s, video work was drying up and writing fiction wasn't paying the bills.
I kept reading the classifieds in the Boston Globe and seeing jobs for technical writers. I had no idea what this was, but if being a writer was part of the job description, then I was half-way there. I looked into a few programs in the area, and in 2002 I completed a technical writing program at UMass. It was a big career change. I was starting way over. It took a few years to land a job, but I eventually nabbed an entry-level position at a medium-sized software company and have been employed ever since.
Writing is not a big part of technical writing. It’s maybe 20% of the job (less or more, depending on where you work). It’s more about organization and research and learning what you are writing about. The product I work on is very technical and is constantly changing and improving, so the opportunity to learn about it never flags.
Questions to ask yourself:
Am I logical?
You don’t have to be an engineer to be a technical writer. In fact, being an engineer is a detriment to technical writing. (That’s not to say every software engineer shouldn’t take a technical writing class—she should, so she can better understand how to communicate all that tasty knowledge about the tools she writes code for.) But you will need to be logical in terms of knowing how a subject should be organized, how to approach writing about a subject (start to finish or easiest to hardest), and what information should and should not be included. I am not logical like an engineer is logical—I can’t always get to point F without forgetting or questioning how I managed just to get to point D. But luckily, I don’t have to be an engineer to write.
Am I organized?
You need to be organized. You need to be good with details and time management. But, aren’t most writers pretty good at this already? It helps to skew a little toward the compulsive side here. On the job, you need to pick up details about consistency. This takes practice, and you probably have skills you don’t even know you have. That’s what happened to me. I had no idea I had capacity to notice details, to be organized, and to learn fairly quickly. It took a technical writing program to make me recognize skills I had but was barely using.
Another part of being organized is file management (on your PC or laptop). Go to your C drive. Is it a mess? Are there files and folders in there that you have never seen? Do you have multiple Documents folders? Are you constantly confused about where you saved things? That was me when I first started tech writing. Man, it was rough. For some reason, this type of logic escaped me. But I was forced to learn quickly where and how to save files. There are myriad formats in the software industry, and you will deal with many of them. Don’t be frightened, you’ll learn as you go.
Am I technical?
I’m not technical. But I can learn. And, of course the longer you’re a tech writer, the more generally technical you’ll get. But you’re not expected to be a master at the technology you’re writing about. In fact, often you shouldn’t be. Usually you need to come to a subject as a novice. That way you approach a subject like most of the users you are writing for: fresh and with a lot of questions. But, you have the advantage of working with the people who can answer your questions. Every time you question how or why something works the way it does, you are learning about the product; incorporate this new information and the documentation will be better for it.
That said, some tech writing jobs insist you be technical. A company like Framingham-based Mathworks wants its writers more on the egghead side, with a mathematics background. Some companies that work in the medical field want writers that have medical writing experience. Generally, when you go in for your first tech writing position, you can spin your lack of technical experience with whatever product or technology they deal with into a plus; you need to learn about it so you can better write about it.
One more thing: There are multiple computer platforms. You are used to Windows or Macintosh. But, you might have to work with UNIX systems. UNIX, and all its many flavors (Linux, HP-UX, Solaris, etc.), is an entirely different kind of computer system. One where you type commands into a basic text editor to access files and run programs. It’s not much fun. It’s really basic but powerful, and programmers and developers love to work on UNIX. So, you will eventually run across UNIX systems. Don’t be afraid, just let it happen. Learn a few basic commands, and everything should be fine. Oh, and you’ll never touch a Mac on the job. Unless you work at a fancy start-up where everybody is 25 and they have unlimited cash resources. …oh wait, it’s no longer 1998.
What tools will I use on the job?
You need to know your way around some word processing programs. Master Microsoft Word for a start. Still, when you’re on the job, you’ll need to learn industry-standard programs, like:
• FrameMaker. A powerful word processing program designed for writing books with chapters and an index and glossary, like user’s guides and installation guides.
• Robohelp, AuthorIT, or MadCap Flare. Online help authoring tools. Also, these tools are used more and more as a single-source environment, where you write and store pieces of content that can then be reused in multiple places. Whenever you update the content at its source, the changes are propagated wherever it is used.
• PaintShop Pro or Snagit. Most of the companies I’ve worked for have had basic graphics programs. These are simple programs that allow you to take a screenshot of the user interface (like when you hit print screen on your keyboard and save a copy of what you see on your monitor) and do some minor edits to it, then drop it into your document. I also have Microsoft Visio, which allows me to create simple or complicated flowcharts or logic trees. Also, PowerPoint can be good to create some simple flowcharts as well.
The Technical Writing Life
Technical writing is not a bad gig. You deal with deadlines, egos, myopic and sometimes uncommunicative (but often very nice and willing to share) engineers, and the pressure of getting the software documentation out the door on time. And in a down economy sometimes I feel like the tech writer will be the first to get axed if layoffs hit. But, since first finding steady work as a technical writer in 2005, I haven’t got laid off. I don’t work crazy hours, and only need to put in more than 40 hour weeks during real crunch times before a release. The high tech industry is still in decent shape (depending on where you live, of course); there are still some tech writing jobs out there.
I get up an hour early most work days to write my own stuff. I also take advantage of weekends to write. Having a job where I write is, in the end, a benefit to a fiction writer. It's like having both sides of your brain available for writing, which side you use depends on whether you're writing a user's guide or a novel.
Showing posts with label editing. Show all posts
Showing posts with label editing. Show all posts
Monday, October 19, 2009
Tuesday, October 13, 2009
Technical Writing Vs. Narrative Fiction, Part 3
Editing
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:
• Structure
• Pacing
• Consistency
• Standards
Structure
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.
Pacing
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.
Consistency
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.
Standards
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)?
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:
• Structure
• Pacing
• Consistency
• Standards
Structure
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.
Pacing
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.
Consistency
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.
Standards
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)?
Subscribe to:
Posts (Atom)