2.3: Technical Writing Research and Writing Process

Technical Writing Research and Writing Process

Below, I’ll be discussing what I see as seven phases of the writing process for technical writing. I use the term phases because these are not really steps, but instead ways of viewing the project that you go through. In general, you go through these phases in order. However, you may jump back to the mindset of one phase or another without ever really leaving your current phase. (You might question purpose, for example, while identifying document goals). Or, you might decide once you reach a certain phase that you need to take what you’ve learned and revert to a previous phase or even the first phase. That might sound horrifying, but some of the best writing comes from those types of responsible decisions. Trust me, if you think it might be best to start over and you don’t, someone else is going to eventually see your text and likely come to the exact same conclusion.

Writing Project Phases

• Phase 1: Coming to a Purpose • Phase 2a: Identifying Research Goals • Phase 2b: Researching Context • Phase 3a: Identifying Document Goals • Phase 3b: Implementing Document Goals • Phase 4: Drafting • Phase 5a: Editing • Phase 5b: Testing

• Phase 5c: Revision • Phase 6: Proofing • Phase 7: Publication

Phase 1: Coming to a Purpose

The first phase of a writing task is often coming to a purpose. Sometimes this phase, like all of the phases, can take a long time. Other times, you can get through the entire timeline in the space of a minute or two (such as when you’re writing a work email).

What usually controls the direct of the first phase is the origin of your writing task—is this something you want to do or is this something you’ve been asked to do. If you’re being asked to do something, you have much less control over the purpose that you’re carrying out. If you’re doing something on your own, you’re going to be able to craft purpose with a bit more control.

Identifying Your Purpose

• What am I doing?

• Who am I doing it for?

• How will they use it?

• What will it be about?

• When will it be used?

• Why am I being asked to do this?

The answer to the above questions will give you a sense of your purpose. You don’t always need to know all the answers to the above, and really you just want a sketch of the answers at this point. But, you need to know the general gist of each of these questions to have a clear idea of purpose. Once you’ve figured these questions out, you should have a clear idea of what you will be doing and who you will be doing it for.

For an example, you might be asked to write a white paper on a new service your company is creating. Below, you’ll find the rundown for this project via the questions on purpose:

What: I am drafting a white paper, an informational and persuasive text designed to education folks enough to know why they should want a service.

Who: I am doing this work for my immediate supervisor, but really this is a service to the entire company and getting new clients helps us keep the doors open.

How: The reader should use this paper to understand our service and why it is valuable and worth having.

What: It will be about our new service that provides on-site minor medical care for construction firms.

When: It will be used in the early part of the sales process. It may be used as a cold-call tool.

Why: I am a technical writer and familiar with the program and our sales process, so I am being asked to write this document.

Notice in the example above, most of what I’m writing is coming from the writer’s own understanding of things. Understanding your purpose, ideally, shouldn’t involve a ton of research. You just need to know the parameters of your project and what is going to be required and what will be recognized as success. These are primarily internal metrics, not external ones. Once you know these things, you can move on to the real work of research in Phase 2.

Phase 2a: Identifying Research Goals

In Phase 2, we move away from the internal understanding of the project we started with in Phase 1 and expand to understand the project from outside perspectives. We’ll also carry out research in this phase, so we’ll really be going past simply identifying. In doing all of this, we’ll be trying to figure out what we need to know to be effective writers in the situation we’re currently in. This phase is a long one, but it is one of the most important steps in good technical writing!

To identify research goals, we need to know what we don’t know. I won’t go into the full Donald Rumsfeld quote on known-knowns and known-unknowns, but we do need to get a sense of what we need to find out. This is a fairly natural course of events if you think about it—what would be the purpose of research if we already knew what we were going to find out?

To help out in identifying what we need to find out, I like to work through a series of questions. (You may be noticing a pattern at this point). Below, you’ll find the first set of questions I often ask:

Identifying Research Goals

• Who is going to be the primary user of this text?

• Who might they consult when reading this text?

• Who might be interested in this text for secondary reasons?

• What laws and regulations will govern this text?

• Who in my organization is going to control the release of this text?

• What will they expect?

In each of the above questions, we’re trying to get at the question of who. We need to figure out the identity of the users of our documents, and we need to know who is going to be assisting them in that use. At first, that might seem like an odd question, but if you examine your own use of important documents as well as workplace practices, it makes more sense.

When you use an important document, you often ask folks that know more about specific parts of that text for assistance. For example, if you’re looking over an application for a college, you might ask someone who has applied successfully to that college or another college for assistance in a particularly tricky part. If you’re in a business situation and you are reviewing a bid for a new service, you might ask one of your employees or coworkers with expertise in a particular part of the package you don’t understand or know much about. In each case, these consultants are not the primary user, but they’re using the text nonetheless.

Once you’ve identified consultants and users, you’re going to want to at least consider who might run into this text for secondary reasons. This might be someone who is a competitor—they want to see your text so they can make sure they’re staying competitive with your offerings. It might be a news organization that wants to report on your business practices. It might even be an advocacy group that has decided you are their enemy! (For example, you might be building a new shopping development near a historic neighborhood full of folks who simply don’t want your traffic in their streets).

The next who you want to identify is the governmental who—which federal, state, and international laws might govern this text? What government agencies might you need to interact with? What will the expect? This question doesn’t always come into play, but when it comes into play, it can be of the utmost importance. There is nothing quiet like running afoul of a governmental agency’s paperwork demands.

Finally, you’re going to want to know who in your organization is going to control this text’s release. This might be the person that tasked you with the purpose you’re operating under. This might be the legal department. What matters is that you know who they are and what they want. If you’ve done your homework in assessing Purpose, this may well be the easiest bit of research.

Phase 2b: Researching Context

Once you’ve identified all of the relevant who answers, you’ll need one more pass to do some actual research. Yep, it’s time for another list of questions. For each of your who’s, you’ll need to answer the following questions:

Research Context

• What does this user need from the text?

• What will be this user’s attitude towards my text?

• What will this user appreciate in my text?

• How will this user’s political situation impact their interaction with my text?

In each question, we’re going to be trying to find out what exactly we need to know when we’re doing our writing of the text. With the question on need, we’re trying to figure out what use is going to look like for an individual user. With the question on attitude, we’re trying to ascertain how we need to present the information to get a good response. With the question of appreciation, we need to know what will win over a particular user. With the idea of politics, we need to know the internal stakes for each user when working with our text. (Note: when we discuss politics in this text, we’re almost always talking about politics in the general sense—what groups exist and how will they respond to our choices? We usually aren’t talking about political parties and elections and the like.)

These questions likely make more sense when they’re given some context. Below you’ll find an example of answering each one of these questions for a primary user in our example of the service white paper:

Need: The user will need to know what we offer, how the service is carried out, what the cost of the service will be, the benefits of the service for their business, and the competitive advantage the service will offer them.

Attitude: As this will be drafted as a cold-call document, it will likely be met with some skepticism. In order to get past this, we’ll need to make the document quite informative for the users and make sure it doesn’t come across as a hard sell from page one.

Appreciation: The users will appreciate timely and up-to-date research on industry best practices. Anything we can do to make the reader feel like they’ve got a better appreciation of what is current and cutting edge in the business will be advantageous. If we can do this without coming across as someone after a sale at all costs, we’ll likely get a good response, even if we don’t get a sale for this service at this time. Building a solid relationship matters.

Politics: We will be sending these documents to the owners of the companies we want to address. There will be generally fewer political hang ups over this because they will be the final decision maker. However, there may be some political issues that arise if the employer already has a service provider for healthcare. Additionally, there could be internal pressure from employees or external pressure from governmental agencies to provide better healthcare for employees on the job site, so this may be something we can take advantage of.

For each of your users, you’ll want to answer questions just like the example above. As you can see, hopefully, these questions are designed to push you to find out information and to put that information on the page. You can also put these questions on a whiteboard for discussion purposes. Often having generative questions can make group writing more effective because it gives you a way to get the expertise out of each member’s head and into the shared discussion space.

Gathering Research on Users and Context

Before we move further into the phases, we should pause to note that the questions above on the context we’re researching are fundamentally different than the internal-facing questions from Phase 1. In Phase 1, we could easily answer questions because they were from our own situation and our own circumstances. In Phase 2, especially in 2b, we’re looking at other people’s circumstances—that’s a totally different animal. You can’t just wing it when you’re answering questions about other people because you aren’t other people. You’re you.

To gather information on other people, you need to actually do some research. Some of this research can be research from academic sources and trade publications. Some of it can be from the experiences you’ve had as well as the experience of others you might be writing with. But, all of that is no substitute for actually interacting with the folks you’re going to be writing with!

In the back of this text, you’ll find several smaller chapters on research methods. You’ll likely need to consult at least one or two of these methods to gather information on the context of your audience/ users. To start off, interviews might be a useful place to begin if you have access to the folks you will be writing for. Read through the various approaches’ introductions and you’ll get a feel for which might fit your situation best.

After you’ve carried out your research, you’ll be in a much better place to make decisions about your audience and writing for them. You’ll be able to ask yourself questions and then have data to answer them instead of relying on suppositions, anecdotes, and hunches.

Section Break - Purpose, Goals, and Context

1. When you write a paper in a course, how do you assess the purpose of the assignment? What helps you in this process? What impedes you?
2. What documents can you think of that, in your mind, represent a firm understanding of purpose but a poor understanding of context? Why?
3. Create two short texts, each with the same purpose, but designed with different contexts. They might be a tweet or an email body message or a text. How do they differ and why?

Phase 3a: Identifying Document Goals

Once you’ve identified your research goals and done some research, you’ll be ready to move on to the next phase of the writing process, the phase where we turn from users and audience to the structural makeup of our text.

When we talk about document goals, you may be tempted to conflate that with coming to a purpose in Phase 1. While they do sound similar, the focus in Phase 3 is on the actual document—the key features of the text and the expectations that readers will have for it. The difference here is that we’re looking at the ways that the actual document, its features and its structure and appearance, helps meet our purpose and satisfy the expectations of our audience. Again, they sound similar but have an altogether different focus.

Document goals come in a couple of forms, each with their own focus and point of view. Some goals are focused on the document’s genre—what kind of document is this supposed to be, and what does that kind of document look like? Others are focused on the way the document’s structure will be oriented to meet the purpose of the text and the audience’s needs and expectations. Taken together, all of these goals help us plan out the drafting of our text to make sure we’re as effective as possible in our writing efforts.

Identifying Document Goals

• What genre will the document be?

• What topics will the document need to cover/convey?

• What types of information will need to be highlighted?

• What accommodations will be needed?

Each of the questions for this phase focus on identifying key aspects of our text’s structure and content that will need to be researched to gain a clear understanding of what will be required. Some of this research can be internal, and some may be external.

Document Genre

For the question of document genre, you will need to look to your internal and external expectations. This may be a fairly simply step—your purpose may explicitly discuss what genre will be required. If not, you’ll need to do some primary research. Look for similar documents in the professional world that carry out the same goal as yours. What genre are the documents? Are they all the same? Are they different? Identify one genre that you feel would best fit your current goals, or make a mashup that meets your own internal goals.

For the question of document genre, you will need to look to your internal and external expectations. This may be a fairly simply step—your purpose may explicitly discuss what genre will be required. If not, you’ll need to do some primary research. Look for similar documents in the professional world that carry out the same goal as yours. What genre are the documents? Are they all the same? Are they different? Identify one genre that you feel would best fit your current goals, or make a mashup that meets your own internal goals.

One example might be the police procedural television show. In these shows, the audience follows along with police officers as they go about their daily work. Not all of these are framed the same way of course, and older shows like Dragnet maintain a focus just on the cases, whereas newer shows may focus more on the people doing the policing and their lives, sometimes even with some comedy added in with shows like Castle or Brooklyn 99. In each case, there are certain hallmarks that are echoed by each show that places the show within the procedural genre. That doesn’t mean that there are hard and fast rules that must be followed—genres change all the time—but, there are expectations that must be met or at least addressed.

Document genres work the same way. When you think about annual reports, tax returns, grant proposals, or even memos, each of these texts play by a certain set of genre rules and expectations. Often you can see similarities between the function of genre examples taken from any number of places, even if the specifics of how the genre works will be tailored to a specific audience and organization.

Fundamentally, document genres (and others really) represent an approach to working with a given text. A genre is the way that a textual problem has been solved. If the solution was effective, it was likely repeated. As time went by, the solution was tweaked to meet challenges the original approach didn’t address. The genre continues onward as a way to meet a challenge until it faces one that it simply can’t address. At that point the genre is either retired or fundamentally overhauled to meet the new situation.

To research genre, you should first look to your purpose. Is there an already present genre in your organization you’ve been asked to create a text within? If you already have a standard format for something like an annual report, use that. You should never go searching for a new genre or a new approach simply because you’re making a new text. Unless the genre is no longer solving the problem, keep it as-is. Otherwise, you spend valuable time you could be writing your document trying to come up with a new approach when none is needed.

If you don’t have an in-house genre, you need to create one. Look at example documents that are doing the same thing your document is doing. What structural choices are present? What kind of language is used (informal vs formal)? Take notes about all of this and sketch out your own model based on the examples. It will be a bit shaky on the first go, but that’s what happens anytime you create a new approach to a technical writing task. This is why versioning and revisions exist.

Topics and Audience

Once you’ve got an idea of genre, you need to think about the topics you need to cover. Look at the purpose of your text and look at your audience and their context. What will you need to cover in order to complete your purpose and satisfy your audience?

For example, if you’re being asked to write a series of instructions on how to upload video content to the web for grade schoolers, you will approach this much differently than if you were writing the same content for a retirement community looking to get their members more engaged with social media. In the first example, fundamental questions about video, the web, and social media wouldn’t need to be addressed. Kids get those things. However, the elderly members of the retirement community may not have a firm grasp of how the web works, how video hosting on the web works, and they may even distrust computers! With that said, both groups would likely benefit from a robust set of tips on privacy, so that isn’t to say each group is totally different.

Make a list of your topics and try to make a note next to each item explaining what you mean and why you think that topic needs to be included. You may think this level of documentation is silly (and it would be for something like a three-sentence email to arrange for your friend to meet you for lunch), but being able to look back and explain to your superiors why you’ve made the choices you did in a document based on research and evidence can be a powerful tool when your choices are called into question or someone wants to know why your work is so successful.

Thinking About Types of Information

We we ask about types of information, we’re really thinking about formatting. What types of information in your text will need to have custom formatting? Will there be keywords? Will there be warnings? Will there be cautions? Will there be movies and books listed? Will you be using non-standard characters a lot, such as names in Arabic or Japanese? Each of these questions is a formatting question.

You’ll want to make a list of each of the types of information that will have a special format. If you want to be exhaustive, you could even include numbers and symbols associated with chemical formulas or mathematical equations. The goal here is to have a handle on what will be represented in the text.

Once you have a list of these types of information, sketch out what your formatting for each will be briefly. Will caution be yellow? Will warnings be red? Will formulas be inline or separate from text? Sketch out those answers now. If you’re not sure, do some research. Look at how others have presented the same data in their texts. If you have an internal style guide, use it. If you have a normal way of doing this in your own organization, use that. Otherwise, do the research and make your notes!

Thinking about Accommodations

When we think about accommodations, we’re trying to identify alterations to the text that will be necessary to make sure our users will be able to use it without unnecessary burdens being placed on them. When we think about accommodations, you’ll be thinking about things like the following list:

• Do we have users with special color needs for color-coding?

• Do we have users that will access the text via a screen-reader that will require image captions?

• Do we have users that will need the text translated into another language?

• Do we have users that will need the text written to a specific reading level?

These questions and others will help you identify any accommodations you might need to make.

Your goal here is to make sure you know any sort of need that will be have to be addressed by your or your organization as you write. In some cases, you will have an office in the organization that handles this type of content. In the US, this type of content usually falls under Section 508 rules and regulations when dealing with government agencies. Other countries and organizations may differ in their approaches.

By approaching accommodations early in the writing process, you’ll be in a better position to ensure your text will serve its audience well, regardless of the way they’ll be reading it.

Phase 3b: Implementing Document Goals

Once we’ve identified document goals, we need to do some research and planning to get those goals ready to draft. We need to explicitly identify what genre means for us in this context, we need to connect our list of topics with a series of sections in the text, and we need to create a miniature style guide for any special information and accommodations that will be needed.

Genre Requirements for Drafting

First, we need to explicitly write down how the genre of our text will work. This usually involves two steps: identifying the specific sections that will be needed, and identifying the voice used in the text. For the specific sections, we’ll need to identify what sections are expected in our genre. Next, we’ll need to make sure we have a consistent voice throughout—this may be casual, formal, or something in between.

For example, if we’re going to be working on an annual report, there may be some expected sections that will be present. Now, we’re not getting to the point of topics and sub-topics here, but we need to know about major segments of the text. For an annual report, there may need to be a special executive summary that will be present. Knowing that needs to be in the text helps us plan our our writing task. There might also be an expectation of appendices with hard data included. Knowing that helps us make sure the document meets the expectations given by the genre.

When it comes to voice, we just need to make sure we know what voice we’re using. This can be the start of our mini style guide. Simply describe the voice and how it should work. Will it be formal with no contractions? Will it be informal with a lot of “you” and other direct address use? Will it be silly? Jot down your goals and then use this later as a rubric for your own writing. This type of work is especially useful when you’re working in a team environment where several writers need to use the same voice to write sections that will be combined into one larger document.

Setting up Topics and Sections

Next, you’ll want to connect your topics that need to be covered with specific sections for the document. You’ll want to sketch out the major sections and then map your content to each area. You’ll rely on your research on the audience as well as your purpose here to craft a table of contents for your text.

This will be a rough outline of the text and may look something like the list below:

I. Introduction

i. Salutation to readers (familiar customer for 10 years)

ii. Background on project (reworking of a project by other contractor

iii. Description of rest of text

II.Project Approach

i. Previous work (Current CEO ordered this work)

ii. Current method (Focus on environmental factors)

III. Project Staff

i. Leadership structure (Emphasize experience)

ii. Team member bios (Structure around leads)

IV. Project Timeline

i. Overall timeline (Focus on Earth Day deadline)

ii. Possible delays and challenges (Highlight variables)

V. Goals and Outcomes

i. Overall project goals (Connect with ongoing relationship and with ongoing relationship and environment)

ii. Rubric for measuring success (Use contract for detailed specifics)

VI. Closing (Personal thanks and contact information)

In the above example, I’ve sketched out a potential structure for a project report that might be given to a client at the outset of the project, presenting the reader with a simplified and accessible version of the existing technical plans that emphasizes the why of what will be going on. In each case in parenthesis are some notes that will be useful regarding the audience and the writing. For example, when talking about previous work, there is a note that the current CEO ordered the infrastructure being replaced. Knowing this, we would want to be rather gentle with our critiques of what is currently being done—there is no reason to throw our client under the bus, especially when that can make the boss look bad to an entire organization.

In your own work, you may want to follow a structure like the above, or you might try something altogether different. What matters is that you come up with a structure for the text that covers all the content you’ve identified as necessary while creating sections that make sense within the genre you’re drafting, sections that will help this text meet your stated purpose. We’re trying to put all the stuff we now know into a plan that we can use for the actual writing work ahead of us.

Style and Accommodations

Last, you’ll want to come up with a mini style guide addition that covers any content that needs special formatting or accommodation. A style guide for our purposes is really just a list of things that should be done in the document to maintain consistency. It doesn’t have to be complicated, but it does need to be clear and accessible those doing writing and editing. We’ll get into this in much more detail later when we talk about project management in a later chapter.

Think about the style guide as the place you go to answer any questions regarding how something should look. When someone is writing a warning, the style guide should give them instructions on how that should be formatted. When someone is including an image, the style guide should list any special instructions for accommodations. The text will work as a reference for your writing, and a living one at that.

Style guides can and do grow over time. Anytime you have to spend more than a moment deciding what something should look like, make a new entry in your style guide. By doing this consistently, you’ll make sure you have a record of the choices you’re making and an explanation of those choices. In a group situation, this allows you to hash out your approach once and then maintain it consistently across multiple authors and perhaps even multiple documents. In the world of coding, you often see a similar documentation alongside code, but also within code in the form of explanatory comments. In all of the situations above, you’re trying to remain consistent and help future you remember what past you wanted done.

The style guide can be fairly simple, as you see in the below example:

Style Guide for Green Infrastructure Project

Voice: The overall voice of this document should be formal, though contractions will be allowed. Formal titles, names, and address should be used throughout

Major Sections: Each major section should be in Impact font, 14pt, bold. The color for each major section should be green (color code should be decided by end of project)

Sub-Sections: Sub-sections should have titles in 12pt Times New Roman and should use italics. The color should be standard black.

Images: All images should include descriptive captions that will be screen-reader accessible.

Revision Log for Style Guide:

Version 1.0 Original style guide added

Version 1.1 Image caption guidelines stipulated to accommodate screen readers as client has several members of team that will be using these devices.

Again, the style guide doesn’t have to be too terribly complicated, but it should be a place you can go to make sure you’re addressing document issues consistently throughout your writing. Making a decision once and then referring back to it makes life simpler.

Section Break - Document Goals and Structure

1. What is your favorite genre of television? What do you like about that genre, and how do you identify it? What boundaries can be broken? What boundaries do you consider to be firm?
2. Pick a genre of text like a report or a memo. Find as many examples as you can within ten minutes of searching online. Quickly catalog the examples. What do the extremes look like?
3. Find a style guide online. What types of information does the style guide contain? Why do you think it is there?

Phase 4: Drafting

Though you might have wondered if we’d ever get here, we’re now at the phase of writing where they actual document comes into shape—drafting. The drafting phase is the most important phase in that this phase actually creates your text, but it can only be successful if it is built upon a firm foundation of research from the previous phases. (And yes, this is even true of short emails with an abbreviated version of the process).

When drafting, you’ll be taking your style guide and section outline and fleshing out the content you’ll be creating. In each section, you’ll want to draft a text based on your guidelines and your audience research. When you wonder how to approach a particular subject, think back to your research on audience and purpose and genre. Any choices you make should be, whenever possible, grounded in research and tied to your users.

When drafting, I find it is often helpful to skip the introduction of your text and to move directly into the body. An introduction is designed to introduce a text, but that is fairly difficult if no text exists. By skipping your introduction and moving into your body you are able to get going on content you can actually create without needing to know the entire document’s content. Once you’ve finished the text, go back and introduce it. It may seem counter-intuitive, but it helps quite a bit.

As you go, think a bit about how you’re saving your text and how it is accessible. You’ll likely want to have at least one backup of your text, and you may even want to save versions as you go. This will allow you to revert to an older copy or an earlier point in the process if you realize you’ve gone in the wrong direction or realize an earlier draft of a section was better than the current one. Saving your text can also be useful when accidents happen. If you lose the device with your text, accidentally delete your current draft, or have a file that gets corrupted, backups make things much less stressful.

Collaborative Drafting

You’ll also want to think about making your text accessible to any collaborators. I won’t go through the trouble of advocating for any particular type of solution to share with your collaborators—these services change and morph all the time. But, I will say that it is ideal to use some platform that hosts files with synchronized updates when you’re doing a lot of work on the same document at once.

If you and your team need to be in the same text at the same time, use a platform that will host the file natively—a platform that lets you edit in browser in real time. If you just need to have the files available, you can use different options that will sync up as you need them to.

Above all, don’t use email! Nothing in life is worse than trying to reconcile multiple files and multiple versions of a text into a final document from a chain of emails. Emailing files leads to poor communication in highly collaborative texts. If you’re editing, it’s not a big deal. If you’re actively drafting, it can ruin your text, or at least your life for the duration of the project.

Finally, as you draft collaboratively, think about voice and tone. Make sure you’ve all got the same supporting documentation to draw on. Make sure that you all have an idea of what the text is supposed to sound like and how it is supposed to relate to the audience and subject. Life is not fun when you get a text with two to four authors and each author has written with a different tone and vocabulary. At the end of that process you’re either rewriting the word choices or putting together a series of texts that simply don’t belong together. Neither is fun. Create a style guide. Use the style guide. Love the style guide.

Phase 5: Editing and Revision

Alright, so you’ve finished your text. Congratulations. Next, you need to make some decisions based on your goals, timeline, and resources. You may wonder why editing comes first as you gaze at this list, as editing is normally treated as a secondary/final concern—you don’t edit something you are going to revise heavily. It all comes down to the decision you’ll make based on the three topics I mentioned at the start of this paragraph: goals, timeline, and resources.

Goals

In some cases, you will want to immediately jump into editing a text when it is finished. Why? Your goal may be to get the text out the door quickly and to respond to a pressing request. This would be a useful workflow if you’re writing an email reply to an important client or member of your organization. You need to get information back quickly in this case, so editing immediately makes sense. You aren’t going to spend too much time on this text because, frankly, it isn’t a major document.

Think about the level of importance of your text—is your goal a simple response or a durable document that will withstand continued scrutiny and use. Some documents just aren’t worth as much time as others. That may feel a bit sacrilegious in a writing course, but it is true. If I’m texting someone a quick reply, it is nowhere near as important as a formal assessment document for a graduate program I might be writing the same day. As such, I should set my goals accordingly.

Timeline

Another item to consider is the timeline you need to meet. Sometimes, you simply don’t have a lot of time. In those cases, you may need to jump directly into editing. In those types of situations, I recommend focusing much of your time on the first two pages. Most readers are going to set their mental image of your in the first few pages; if you have a ton of errors in that space, they are not going to like you very much. However, if your first two pages (or first page even) are immaculate, then you’re going to get a less critical reader that will forgive more later in the text. In short, you don’t want to trip the “gotcha” response in your reader. If you start out with tons of errors, then it almost becomes a game to find more. If you start out flawlessly, the text becomes a narrative rather than something to be read critically while looking for errors.

In situations where you have ample amounts of time, do not edit first. To do so would be a colossal waste of resources and time. Editing is hard work and it takes a lot of focus and time. You don’t want to spend an hour editing three pages that get deleted from the final text or entirely rewritten after testing. If you have more time than a few moments, save editing for last!

Resources

A final consideration is resources. You may note that in the middle of the next section is a testing phase. Testing is an ideal step in any technical document that will be used. There is almost always a gap between what happens in the writer’s head and what happens when the text is used. Sometimes that is a gap that has been created because the author is so familiar with a process they skipped a step. Sometimes it is simply a mismatch in terminology between an interface and a document. In any case, testing is very useful. But, it is not always something you have resources for.

Testing really can run a spectrum, something we’ll talk about later and in the final segment of this text with research method, but sometimes there just aren’t any resources to carry out testing. That may be because of budgets or timelines, but it can also be due to institutional views of the writing process. Some organizations simply don’t have testing on their radar as something that is done in technical writing.

In cases where testing is not feasible, go through the text as closely as you can. Think about how accurate the text will be for its intended use. Read the text aloud if at all possible—this catches more errors than you’d realize because of the way we read texts of our own creation. Once this is done, move along to revision or editing, depending on your timeline and goals.

Phase 5a: Editing

Editing, as we discussed previously, is going to be your last phase in virtually any writing context. Even when you briefly look over a text before you send it, you are in essence editing. But, it comes first in this list because many times when you are writing you will simply stop here. There won’t be time or need for testing or revision. And, as we discussed—that is okay.

When we talk about editing, we usually think about two types of editing—copyediting and comprehensive editing. In some situations, you’ll just do copyediting. In other cases, you’ll be doing comprehensive editing that goes much further. Think about your goals, timeline, and resources when you make this choice.

Copyediting

Copyediting is simply looking for issues in the text related to grammar, structure, and content. Does the text do what is says it will? Do the sections come in the correct order? Are terms used consistently? Is structure consistent? Is the grammar okay? Is the spelling consistent and regionally-situated?

In copyediting, you are looking at the text as a finalized document that needs some checking on the textual level. In a fast-paced environment, this is a quick glance. In a slow-paced environment, this may extend to checking terms in a style guide for consistency with institutional norms and spellings. (For example, if you have British and American clients, you need to standardize color or colour). As in everything, think about your goals, timeline, and resources.

When carrying out copyediting, you want to ask the following questions of the document before assessing the document via these questions’ answers:

Copyediting Question

• What does the document say it does?

• What sections does the document say it contains?

• What is the voice of the document?

• How is the first section formatted?

Once you have these answers, you can then assess the text. I recommend you move through the questions in the order listed above using the answers you’ve generated as a standard for testing.

For example, if the document says it will teach you how to true a bicycle wheel, does it actually do that? Can you understand the process by reading through the text? If not, you need to revise accordingly. In cases where you are the author, this is simple. In cases where you are simply an editor, pass it back to the author with instructions on what to add.

As another example, the text might reference an appendix that includes a conversion chart for converting dosing from milliliters to teaspoons. Does the text actually have that appendix? If it doesn’t, that calls for revision as well. (Or maybe just locating the lost file).

With something like voice or formatting or term use, you want to go by the start of the text versus the rest. (This is based on the assumption the author at least got the first bit the way they intended—that isn’t always true, but it can be a good strategy). If the document starts incredibly formal and then swaps randomly in one section to being informal, that requires revision. If the text has blue headings for the first half, it doesn’t need to suddenly swap to green with no reason,. The same goes for calling a process by one name and then swapping to another. In technical writing, there is no real need for creative re-naming. Consistency and intelligibility are more important than keeping things fresh and new.

Comprehensive Editing

Comprehensive editing is much more involved than copyediting—make sure you have time and resources and it meets your goals. In addition, make sure you do the comprehensive work before you copyedit! Just like with editing as a whole, copyediting is listed first because many times that will be where you stop due to limits in time, resources, or a mismatch of goals with the process.

Instead of looking at the details, comprehensive editing looks at the big picture. Does the document stand together? Does the order of the text make sense? Is the correct audience being targeted here? Should the current sections stay in the text, or should something be added or removed? All of these questions are fair game!

With comprehensive editing, you want to query the document based on the purpose and audience.

This can be as wide ranging or as narrow as you have time/desire for. The following questions can be useful in this process:

Comprehensive Editing Questions

• Who is the primary audience?

• How will their context impact their reading of the text?

• Who might be a consulting audience?

• What aspects of the text might need to be tailored to them?

• What is the purpose of this text?

• How does this text fit with other texts in the organization/genre?

Once you have these answers, you can start to comprehensively edit the text. Using these answers, you have a rubric for grading the text’s content, formatting, and style.

To narrow comprehensive editing to something that fits within this sub-section of the book—I teach an entire course on editing—you can follow the following steps as you go through a comprehensive editing:

1. Check to make sure the text has everything the audience is going to need. If the audience is made up of novices, make sure the text has ample explanation of technical terms. If the audience may need additional resources that will be hard to fine, provide them for the audience
2. Make sure the text is appropriately ordered to carry out the task at hand. Sometimes when we write texts, we don’t always write in the best order for use. Think about the way the text develops. Does it build from one section to another? Does one section later in the text need to be earlier for a section to make sense? If so, consider moving it!
3. Analyze the voice of the text—does it make sense for the subject and audience? Think about who your audience is and what they will think about your subject. Is the choice of voice appropriate? If you have a skeptical audience, you likely don’t want to have a super-excited voice that doesn’t critically engage with your subject matter. On the other hand, if your audience already agrees with you fully, it wouldn’t make sense to be skeptical of everything.
4. If the text has multiple types of users, make sure they can stay in their lanes. Sometimes, a text will have a variety of users that will have different skill levels. In those cases, you need to be wary of how the text is formatted for their use. For example, if you have expert users that know terms and processes, you won’t want to label each and every step and process—your expert users will get exasperated quickly. Instead, think about how you can signal that content is for new users. With instructions, you might have a bold, simple instruction for each step of a process that caters to advanced users or those referencing the text. Under that bold text, you can include normal formatting in paragraph form or just a few sentences that explains what the step means in detail for those who are learning for the first time. Pretty meta, huh?

Once you are done with copyediting, you’ll want to revise. If you have time, editing again can be useful, though at some point you’ll want to switch from comprehensive to copyediting. You can continually comprehensively edit a text forever. Find a stopping place that honors your goals, timeline, and resources.

Section Break - Editing and Drafting

1. When does a document warrant comprehensive editing versus simple copyediting? Come up with some criteria to help judge when a document commands enough importance to require comprehensive editing.
2. Rank the platforms you prefer for group writing, naming your top three. What influences your preference? What features matter when you’re writing with others?

Phase 5b: Testing

Testing is the middle step of our process, though if you have a great deal of time, it may well be the first one—it depends on your purpose and audience for testing. Testing can have different permutations depending on your resources and timeline. You might simply do internal testing with folks in your organization testing out your work. Alternatively, you could actively recruit testers in the generic sense to go over your text. Or, you could get the actual users that will use your text to test it—and those could be internal or external, depending on what you’re writing.

If you are simply passing something along for internal testing, it is more likely that you might send it directly to testers after drafting, or perhaps after a quick edit. With internal testers, you don’t have to be as concerned with the polish and finish as you might with external testers—they won’t be judging your organization based on this text. However, in some cases where the politics of internal testing are fraught (such as cases where the testers see all of this work as silly), you may want to make sure the text is exceptionally polished.

With external testers, you’re going to be either finding folks that fit a generic profile of users or you’ll be finding the actual users to test with. In each case, you’ll want to make sure the text is polished and doesn’t reflect badly on your organization. With a generic profile, you’ll just want to find folks that will fit a certain set of parameters to test your text. These may be individuals with similar age ranges or skill levels as your users. Or, it could just be the general public. With actual users, something we’ll cover later in this chapter in more detail, you’ll be working with the folks who would be using your text to make sure it works as intended.

Testers can be paid or unpaid, but in each case you need to treat their time and experience as valuable. If you pass along a text riddled with errors that looks like a joke, you’re going to be wasting your time and theirs. If you go through the trouble of testing a text with outside users, at least make sure you have a polished text!

Goals of Testing

When you’re doing testing, you’re asking folks to use texts as they are intended; in the process of using them, you’re hoping to find problems with the text. You might find that there are terms that are unclear to the average user. You might find an important step is mislabeled or omitted entirely. In each case, you’re trying to figure out what happens when your text actually gets used the way it would after it leaves your desk. It may seem like overkill, especially since you’re reading this text in a college classroom environment, but testing can save you and your organization time, money, and reputation losses associated with sending an awful text out into the world that simply is not fit for use, or in a worst-case scenario, dangerous.

Later in this chapter, and in the end of the text, we’ll get into the specifics of testing. For now, here is a general workflow you can use for testing:

Testing Workflow

• Identify what you want to learn from testing

• 6Find users that will be testing your text

• Have the users make use of the text in ways that will help you learn what you want

• Record or observe this use, or have the users self-report

Take your findings into the revision process or editing process, depending on the changes needed

With the above workflow, you can get a rough idea of how you can update a text to better fit the intended workflow it will be part of. Later, we’ll dive into this with considerably more detail with specific research methods.

Phase 5c: Revision

So, it has come to this. For many writers, revision is a bad word. Revision is failure to launch, failure to generate a good text the first time. Nothing could be further than the truth. Revision is central to the production of great writing—almost no one gets it right the first time. In fact, many of the most trusted types of texts, such as peer-reviewed academic work or works published by major presses, are produced in environments that are designed to lead to revision and reflection by the author!

Now, as a note—revision and editing are different in this text, and in general practice. Revision often happens when an author reflects on a text. Editing usually happens when an outsider or a non-author reflects on the text. Sometimes revision will incorporate the suggestions of an editor and will be guided by reviewer feedback. Other times, it is self-contained.

When it comes to revision, you can think about it on two levels: global and local revision. Global revision comes first and involves looking at the big picture of your text; in many ways, it is the author’s side of comprehensive editing. With global revision, you move paragraphs, you check to see if topic sentences are supported by the rest of a paragraph, you delete content or add content as needed. With local revision, you focus on small-scale stuff. Does this sentence sound right? Is this the correct word? How can I fix this comma splice?

For carrying out revision, you want to first make sure you have ample time to actually revise, and you need to make sure you’re doing it right. In regards to time, if you are pressed for time, you likely will need to focus more on local revision—large-scale changes to a text can create large-scale problems. If you don’t think you have time for a total overhaul, don’t half-overhaul. Focus on fixing what is there rather than altering it dramatically. If you do have time, focus on global before local. As with comprehensive and copyediting, you don’t want to fix something small that will be deleted later because the larger component it is part of has been removed from your text.

Much of the work of revision maps on top of the work of editing—usually revision and editing are separate parts of a process. Editing identifies the issues, and revision fixes them. (Every editor varies in how much work they do and how much the author does. At the least in modern workflows you’ll have to approve changes in your text). In the case of a single author, you often do both at the same time. Your global revision and comprehensive editing are one and the same. In larger organizations, this is broken up into individual roles with different folks doing different parts of the work.

Carrying out revision effectively takes practice—you learn how to best respond to your own writing by responding to your own writing. There isn’t one workflow that works best, but below I’ll provide some checklists for global and local revision to give you a starting point. Not all of these suggestions will fit every situation, but consider them a good starting point that you can adapt to your own writing. (For example, you might notice after a while that you tend to create a lot of extra “is” formulations where instead of saying “this takes practice,” you say “this is something that takes practice.” In cases like that, you’ll want to focus on finding these “is” formulations because you know that is your kryptonite).

Global Revision Checklist

• Is there a document map?

• Do the major sections follow the plan of the document map?

• Are there sections that shouldn’t be in the document?

• Does each paragraph have a topic sentence?

• Does the rest of the paragraph match up with these topic sentences?

In the above checklist, you focus almost entirely on how the document and paragraphs are structured. The idea is that the document map is your starting point—it tells you what should be in the text and the order that those things should be in. You’ll then audit the rest of the text based on that map before descending to the paragraph level and treating each paragraph’s topic sentence as a document map for that paragraph, auditing each paragraph’s sentences to make sure they fit with that text’s purpose. You can add in some of the extra checklist items from comprehensive editing if you’d like to make this more thorough.

Local Revision Checklist

• If you have time, read the document aloud.

• If you are pressed for time, read the first page aloud

• Search for errors you know that you often make

• Double-check terms that are important for the text

• Work on re-writing sections (important ones especially) that you feel have poor flow or read badly

In the second checklist, you’re focusing almost entirely on small-scale issues. Reading the document aloud is central to effective local editing (and copyediting many times), because it forces you to actually read each work. Often times when we read, we skim without realizing it. When we read our own work, we tend to both skim and edit the text as we read; we read what we meant rather than what it says. Reading aloud gets around both of these issues and helps with the problem most of us face— we can’t stand reading our own work. You can also have your word processor read to you, but I find reading aloud keeps you more focused and able to catch errors

Phase 6: Proofing

Proofing is a phase of the writing process that many guides and writers overlook, but it can be the most important one when it comes to costly mistakes and embarrassing errors. You’ll sometimes see it called proofreading. Proofing involves the creation of proofs—samples of your final document with all of the production choices and text choices put into the form they will have in publication.

Proofing is valuable because it can catch errors that won’t show up in the drafting process alone. For example, you might think that a certain color combination looks great with a certain type of paper when you’re drafting, but when you actually get the printed proof, it looks awful and the colors clash. Or, you might have accidentally used an RGB color code when you should have used CMYK and your text or document has colors that are nothing like what you expected and planned for. Or, you might realize that a choice of font size or style simply doesn’t allow for easy reading when placed into a real-world document. Proofing helps you catch these errors before you’ve paid for an entire run of a document.

In college writing, proofing is not something you run into that much. Most of your writing in classes is often in an office-style program that will go to your professor. Most technical writing, however, goes to outside audiences that will be using your texts. Whereas proofing doesn’t usually make sense in college settings because you rarely get something professionally printed and put together, it is a must in professional settings.

Proofing can be very project-dependent, but a few suggestions can help when you’re looking over a proof. We will cover proofing again when we discuss the production process later in the text.

Proofing Checklist

• Do all of the images look correctly colored and free of pixelation?

• Are all fonts correct or have some fonts been substituted for incorrect ones?

• Are the colors accurate?

• Is the paper correct?

• Is all content on the page, or is some content cut off due to being too close to the binding or too close to the edge of the document (the bleed region)?

• Can the document be read easily

• Are there any errors in formatting or spelling or grammar?

By following through with proofing after final revision, you can catch some last-minute errors and mismatches between what you hoped to find when you created your document and what you find in front of you. Again, proofing is about saving you money and embarrassment—you don’t want to print a run of hundreds or thousands of pages with really awkward and obvious errors throughout. Even the best editor will miss some errors—proofing gives you a chance to catch and replace those before you pay money to get them printed and sent out to your users.

If you want to take things to the next level, you can do some proofreading as well. Proofreading as part of the editing process involves taking the last version of the text that was editing and reading through it and the final proof concurrently, looking for situations where changes that should have been made didn’t make it into the final document.

Phase 7: Publication

Congratulations—you did it. Publication is the final phase of the writing process, a process you may have thought would never end in this text. With publication, you are confident in your text and your proof and you’re ready to send it out to the world. Often publication is a matter of logistics and delivery—you want to make sure the write amount of documents get out to the right people at the right time. We’ll cover publication more in Chapter 6.

For publication, you have a fairly simple checklist:

Publication Checklist

• How many copies do I need?

• Who needs a copy of the text?

• When do they need it?

Once you’ve made sure you’ve got your bases covered, the writing process for your document is over! Congrats—it got published.

Section Break - Testing, Revision, Proofing, and Publishing

1. Carry out some basic testing on an institutional website of your choosing. Pick a website from your institution you are familiar with and have someone else in the class that isn’t familiar with the site carry out some tasks. Make note of how they perform and where they have issues. Prepare a brief report on the test that you could pass along to the webmaster.
2. Revision can be a struggle for almost any writer. What do you struggle with during revision? What tactics do you use to avoid these struggles or to overcome them? Share with the rest of your class and look for common ground and new strategies for succeeding.