Effective Technical Writing

Whatever you are writing, it’s important to remember that writing involves many steps. Many people think that when you sit down to write, whether a technical document or a novel, the words should flow seamlessly onto the page and then you’re done, with wmaybe a pass to check for typos. The reality is more layered. It’s more like doing a jigsaw puzzle…with no box top to show you what it’s supposed to look like when you’re finished.

So how do you find your way when the way is unmapped? Remember that multiple drafts are your friend, and each draft serves a different purpose.

Draft 0_Before You Start Writing
Have a clear sense of how the document will be used and who will be using it. That will help you determine what information you need to include. Before you begin writing, consider these questions:

What is the purpose of your document? Technical documents are not intended to be read like a novel or a New Yorker article. Their purpose is to help the reader make a decision or take an action. What is your document meant to do: analyze possible design approaches, document your methodology, present a vision for a project, convince a potential client you are the right team for their project?

Who is the audience? For your document to be useful, the readers must be able to understand the ideas in it. Keep in mind that the general public, government officials, and business owners will have different knowledge, assumptions, and technical backgrounds than design professionals. Write so that your ideas can be understood by all readers.

Draft 1_Getting Started: Use a Template
Getting those first words on the page is one of the biggest hurdles in writing. The solution: Don’t start with a blank page.

Use an existing template. Find documents in the office with a similar purpose and audience and use them as a guide to determine what type of content to include and how to organize it. Spend time analyzing the documents: Make a list of the different sections, the type of information found in each, and the order in which the sections fall. Make note of the visuals used to support the information. Then list the sections and graphics relevant to your document and add those specific to your project.

If there are no templates to work from, create your own. Start your template focused on the audience and purpose to make sure you include the necessary sections. A proposal (where you are trying to convince a potential client that you are qualified for a project) will require different content than a vision plan (where you must document the background, existing conditions, visioning process, the plan itself, and any supporting materials). List the different types of information you need to include. 

Organize from the general to the specific. Once you have sketched out the type of content you need, focus on how to best organize it. Ever notice how a mailing address goes from the specific (the person’s name) to the general (the city and state)? There is a logic and hierarchy to the way the information is presented. In a technical report, logic and hierarchy are what make a document easy for readers to navigate—and easier for you to write. Unlike a mailing address, however, a technical report usually starts with the general, like an overview of the purpose of the project and/or document and progressively moves toward the specific.

Once you have a template, begin plugging in the information. Once you know what sections your document needs, you can start filling in the information and graphics. You are not required to write in sequence from start to finish. When you put together a jigsaw puzzle, you don’t work methodically from left to right or from one corner to the opposite corner. You place the pieces as your eye locates them. When you have an idea for a section, jump to that place and get it down. It may lead to more ideas about that same topic, or you may find yourself jumping to another section. Follow the inspiration. As you work you may find that the way you organized the document needs to be modified: Some sections may need to be combined, others may need to be broken into multiple sections, and new sections may need to be added. Cut and paste is your friend. Keep writing until you are out of ideas. If the schedule allows, put it down for a day or two. Reviewing your document with fresh eyes almost always reveals what more needs to be done. 

First, not final. The purpose of writing your first draft is to discover what you want to say. It’s rare that someone sits down to write knowing all that should be included. Strange but true. Don’t hold yourself to unrealistic expectations about what the first draft should look like. 

TIP: 
Banish the critic. The first draft is not the time to be concerned about grammar, spelling, sounding like a poet, or any other self-critical notions. The whole point is to get your ideas down unburdened by self-consciousness or self-doubt. If you hate your first draft, congratulations, you're normal.

Draft 2+_Revising: Where the Magic Happens
Once you’ve added all the information you can think of you are ready to start revising. Contrary to what most think, the real writing happens when revising. The first draft is about discovering what you want to say. The subsequent drafts are about refining the organization, analyzing the content to see where it is incomplete or extraneous, making your ideas clearer, and correcting grammar. 

Ask questions. Look at your document as if you were the reader seeing it for the first time. Ask: 

• Does the document fulfill its purpose? Does it persuade, explain, and/or analyze effectively?
• Is the document organized in a way that is logical and easy for readers to follow?
• Have you told your readers all they need to know in order to understand your ideas?
• What information is unnecessary and should be deleted?
• Within each section do the ideas logically flow from one paragraph to the next?
• Is each sentence clear and understandable? Is what you mean to say actually what you say?

Speak to your audience. Is the content written in such a way that the audience will understand it? There is a reason this question is broken out from the others: Your audience is the reason you are writing this document. If their needs aren’t fulfilled, then the document hasn’t done its job. Remember that readers will likely have different knowledge, experience, and needs than you. Write to fulfill their needs in a way that is accessible to them. If your audience contains nondesigners, consider what explanations and information they may need that your design peers do not.

The logic of multiple drafts. To avoid overwhelming yourself, focus on one question per draft. Notice how the above questions go from the big picture (the organization) to the details (the effectiveness of each sentence)—with special consideration given to speaking to your audience. Work through the document section by section focused on one question at a time, trying to see through the eyes of your reader. Rewrite sentences, delete extraneous information, move sentences and paragraphs around, break sections up, or combine different paragraphs into new sections. This is the time to get your hands dirty.

 But life doesn’t unfold linearly.  Don’t be overly rigid about focusing on only one question per draft. If a confusing sentence jumps out at you while you are analyzing the document’s organization, correct it—so you are not distracted by trying to remember to do it later. (Or in Word insert a comment to remind yourself to come back to the sentence later.) The point is to realize that revising involves looking at the document from different angles. Your revisions will be more thorough the fewer angles you focus on at one time.

Almost There: Enlist Other Eyes
After you’ve completed multiple drafts and feel you have done all you can to make the document the best it can be, it’s time to see what others think. Everyone—even professional writers and, yes, even editors—needs feedback. It’s difficult to see the shortcomings in our own work. Plus, most subject matter experts aren’t grammarians—you’re not meant to be. If your firm does not have a formal review process, seek out others who can help you.

Two types of reviews: An effective quality control process involves two steps: a design professional (ideally someone who is not on the project team) to review the technical content for accuracy and completeness and an in-house or freelance editor to review the document for clarity and grammar/spelling. Consider when in your draft writing process is the most strategic time for the technical review. It can be beneficial for you to receive this feedback before you’ve completed your final draft to ensure you are on track and to prevent major revisions late in the process. When you feel the document is complete, it is time for the editor to do a final polish for grammar, punctuation, flow, clarity, and adherence to any in-house or client-required guidelines. 

It’s about collaboration, not judgment: It can be intimidating to show your writing to others, especially if you’re new to writing. Think of it as a team effort. You are bringing something to the table that others can’t (your knowledge of the project), and they are contributing their expertise.  Everyone’s goal is to produce a successful document. Another benefit of feedback is that it makes you a stronger writer.

TIP: 
Leave enough time for the revision process. Revising takes the most time. Make sure to build ample time into your schedule.

What aspects of technical writing do you find most challenging?

---

Click here to download a PDF of this article