The Technical Writer’s Role in Document Development

THE TECHNICAL WRITER’S ROLE IN DOCUMENT DEVELOPMENT

If you’ve ever been charged with producing technical manuals or documents, you know how important it is to ensure that they’re written in a clear and concise manner.

But what if you’re not a writer? Or what if you are just too busy to get the job done? That’s where the technical writer steps in. 

Technical writers specialize in writing and editing documents that include precise, detailed explanations, specifications, or instructions. These documents require technical accuracy and clarity and are often written for a specific audience that may already have extensive knowledge in the subject of the document.

Tech writers are valued in many industries, including engineering, manufacturing, medicine, aerospace, oil and gas, architecture, finance, and IT.

They may help develop instruction manuals, product manuals, Standard Operating Procedures (SOPs), articles, whitepapers, Requests for Proposals (RFPs), and proposals.

In addition, technical writers frequently assist in developing or revising requirements and specifications, including those for materials, hardware, structures, and maintenance.

What to Expect When Working With a Technical Writer

A technical writer is likely to be a left-brained thinker and a stickler for details. A tech writer also:

• Listens carefully and takes notes.
• Analyzes written input carefully and logically.
• Actually likes organizing sentences, paragraphs, and documents.
• Takes pride in making writing consistently and error-free.
  

A tech writer asks questions. He or she actually likes to hear your explanations and learn from them. This is to your advantage.

A tech writer may ask a question about your content that you’ve never considered. Something might be perfectly clear to you, but, as a result of the tech writer’s question, you may realize that the existing verbiage could be misinterpreted.

Are you still wondering how a tech writer would fit into the process or help out your team? Or are you wondering how adding the cost of a tech writer will pay off in the long run?

We’ll explore three scenarios to answer these questions.

Scenario 1: The Document is All Yours.

First, let’s assume you’re the document originator, and you’ve got a draft already prepared or an existing document you just revised. You’re ready to turn it over to the technical writer.

Upon receipt of your document and whatever instructions you provide, expect the writer to ask about the deadline. If your document is hot (a high priority or one with a quick turnaround), tell the tech writer up front.

The writer looks to you as the Subject Matter Expert (SME) or project manager, so provide the name and specialty of any other SME associated with parts of the document so that the writer can direct questions to the right person.

Expect the technical writer to:

• Respect the information in the document. A good technical writer’s most important tenet is to retain the SME’s meaning in every sentence he or she touches. The writer will take extreme care not to introduce an error by misconstruing the meaning of the input he or she has been given.
• Respect your time. The tech writer will first research his or her questions by using the Internet and any relevant corporate documents. If that doesn’t resolve the questions, the writer will usually compile a list of questions so that they can all be answered in one interview. If an interview is not necessary, the answers may be resolved in a few carefully worded emails.

If the writer feels comfortable that he or she understands the content well enough, the writer may wait until the edits are made and ask any remaining questions at that point.

What’s next? 

If using in Microsoft^® Word, the writer will have used the Track Changes feature to show the additions and deletions that have been made. Or, if using Google Docs, changes can be found in Version History.  

There will likely be questions and/or comments in the margin of the document. You can add your own comments and either accept or reject the changes that have been made. If you’ve never used Track Changes, there are lots of how-to articles and videos on the Web, including one that’s short and sweet at YouTube LinkedIn Learning.

You may not be crazy about wading through the markup to determine whether everything has been communicated correctly and you like the results. You may not like switching back and forth between the views. Perhaps you haven’t yet mastered the Track Changes feature.

If any of these is the case, simply request that the writer send two files: 1) a file with only the questions and comments showing and 2) a file with all the changes marked.

That way, you can read from a clean document and only use the other file if you need to go back and check on particular changes. Just make sure to tell the writer how you like to review changes.

After you have reviewed the changes, the writer will incorporate your changes and carefully proof the document once more. According to your instructions, the writer may return it to you for final review before they send it to the final recipient or post it on the appropriate platform.

What kind of changes can you expect the writer to make?

When you receive the initial edits, the tech writer will have:

• Corrected any errors in grammar, punctuation, usage, sentence structure, and typos.
• Spelled out all acronyms at first use.
• Used formal English.
• Eliminated redundancy.
• Adhered to your company’s (or your client’s) style guide and a more comprehensive style guide such as The Associated Press (AP) Stylebook or The Chicago Manual of Style.
• Reorganized sentences for optimum clarity.
• Revised the order in which information is presented (if necessary) to provide optimum clarity and flow.
• Ensured that terminology is used consistently throughout the document.
• Applied the registered copyright, registration, and trademark symbols on first use.
• Broken down the information into numbered steps and bulleted lists.

Why this last one–why change it from paragraphs to bullets?

Technical documents are often not read word for word. Instead, the reader is frequently looking for one specific piece of information.

For instance, the procurement professional may be looking for the temperature at which the aluminum must be annealed. The refinery operator may be looking at the maintenance requirements for how often a certain component must be removed and replaced. The young safety inspector may be verifying the permissible exposure limit for silica dust.

In such instances, professionals should not have to wade through a long technical document. Bullet points and steps help readers scan.

Bullet points and steps also open up what technical writers call “white space.” White space is any area on the page where there is neither verbiage nor graphics.

Hurleywrite.com explains that white space reduces clutter and makes content easier to read. It improves comprehension, increases memorability, and boosts reader satisfaction.

Are there other things a technical writer can do to improve the document?

Depending on the length, content, and type of document, the writer may:

• Recreate/reformat tables, diagrams, and flowcharts.
• Add images from the Internet.
• Format the document in accordance with the company style guide.
• Create a table of contents, an acronym list, a list of references, and/or added illustrations.
• Develop a custom template underlying the document so that all documents of the same type that are written or revised in the future are identical in format.

Despite this somewhat lengthy list of changes, you’ll find that all of your information is intact and packaged in a way that will provide clarity, precision, and utility.

Scenario 2: The Document Has Not Been Written.

Again, you’re the SME, and you need a new document, presentation, or internet content. Given enough information, the technical writer can develop a draft for you. Here are two examples:

1: Your company has a number of documents about the same thing. Some of the information is outdated. It has been suggested that the documents be combined into one. You can relieve yourself of the headache of paring it all down, cutting and pasting, and organizing. Give the documents to the tech writer. Then, from the one document you get back, you can provide comments and make changes that the writer can incorporate and edit.

2: You’re headed out of town or you’re tied up with something that’s come up unexpectedly. You have a meeting coming up, and you need a new PowerPoint^® presentation or talking points.

Provide the writer an outline or, while the writer takes notes, just talk about your ideas and what you want to emphasize. The writer can create your presentation using that information, any documents you’ve provided, and, when appropriate, information and images from the Internet.

Scenario 3: The Document is a Team Effort.

For the third scenario, we asked veteran technical writer Michele Baldwin to comment on her experiences working with teams in developing documents. Michele works for a global engineering company in its Energy Services sector. Her comments are interspersed throughout this scenario.

Now, let’s assume you’re the project manager. You’re responsible for creating a new document or managing the complete revision of an existing document.

The document encompasses requirements for several disciplines or groups within the company. A number of SMEs need to be involved to offer their expertise and ensure that the information correctly applies to their department or field. There are a couple of ways to proceed.

1. The hand-off method

In the case of a wholesale revision to an existing document, you can first make the changes that you know are required. Then pass the document off to each SME in turn until the document includes all of their revisions.

Beware of the endless review cycle. When reviewing documents at their desks, experts may be preoccupied with other projects or events and may, without realizing it, think, “If I don’t catch it, someone else will.” Even with the best intentions, priorities can get in the way, and the document may languish on an SME’s desk for some time.

Another drawback to this method is, as Michele points out, “One SME will note that another SME should be asked about something. Then the document may have to be routed back to the other SME. That just adds more time to the review cycle.”

After the SMEs have reviewed the document, a technical writer can help by incorporating the review changes. But the writer cannot decide whose comments/revisions to include when they are changes to the same sentence or paragraph, and that is invariably the case. As the project manager, you’ll have to make those decisions. 

After the changes have been incorporated and the tech writer has proofread the document, each SME then reads the document for approval. More changes are inevitable, and again, you may have to decide which changes to accept.

In this scenario: 1) a lot of your time and effort is involved, and 2) unless you can exert a lot of pressure and/or dictate what tasks take priority for the reviewers, the process can take a long time because of SMEs’ other responsibilities.

2. Team meetings

An alternative to the hand-off method is to conduct team meetings in order to produce the new document. Team meetings do four things:

1. They take a lot of the task off of your shoulders.
2. They clarify which edits will be incorporated.
3. They eliminate the need for a lengthy review process before document release.
4.  They ensure buy-in among the participants.

Surprisingly, they may also result in getting the document out more quickly.

Team meetings take the team away from things that preoccupy and interrupt their attention to the document. Team participation ensures that team members are engaged in the process and thinking about the significance and ramifications of each sentence.

Michele sums it up by saying, “Team meetings promote discussion. Discussion among experts results in a better document.”

It sounds easy enough. So, why should you include a technical writer on the team?

In the meetings

There are multiple ways of collaborating as a team, of course, but in this example, the tech writer arrives early and sets up to project the document from his or her laptop onto a screen. Team members then read and discuss the document one paragraph at a time.

The writer incorporates the first change, editing, if necessary, while typing. The writer then waits for any subsequent discussion.

When the discussion of the paragraph is over, the technical writer adds the additional changes to the document on the screen. Team members then reread the paragraph, indicate they’re satisfied, and move on the next paragraph.

Michele considered her role in team meetings as that of a scribe. When asked about the writer facilitating the meeting, Michele’s explained, “Trying to facilitate the meeting breaks the writer’s chain of thought in making notes and being ready to add to or change the document in real time.” 

Meetings are usually set for an hour in length, and they should not be allowed to run long. Michele asserts, “Team members have lots of responsibilities, and that should be respected. Team members need to come into each meeting feeling positive about the team and not worrying about how long the meeting will last.”

Michele recalls her experience on a team that developed a specifications document for pressure vessels. Before the team ever met, Michele was charged with combining five documents—both client and industry documents—into one.

“After being asked, ‘Where did that come from?’ at the first meeting, I added the names of the source documents in the margin beside every paragraph.”

So, Michele not only created the draft by compiling and organizing information from five documents, she also carefully did her homework so that any questions about sources that arose in subsequent meetings could be answered quickly.

Between meetings

After each meeting, the tech writer proofreads paragraphs that were changed in the document, making any small edits that are necessary. The tech writer ensures that the formatting and page flow are accurately maintained, and the table of contents reflects the changes. 

When the team’s work is finished

Michele noted that the various document development teams she had been on “usually took about four to six meetings to complete the team review.” Despite the possibility of six weeks of review time, when asked whether she thought the team meeting process was the more efficient way to review a document, her answer was an enthusiastic “Yes!”

When the team has discussed the entire document, the tech writer proofreads, polishes, and proofreads the document again. The tech writer sends the document to you for final review and approval, and if there are any additional changes, the writer incorporates those changes, proofs it one more time, and returns it to you.

The tech writer may, per your instructions, load it in the corporate database and send a notice to a distribution list within your organization or release it to the client, if applicable.

Time, Money, Quality

A technical writer saves you time by taking part of the work off of your plate.

You’re no longer saddled with editing, formatting, and proofreading, and you now have that time to devote to your “real” job. With instruction and existing documents, the tech writer can even save you the time it would take to develop the draft for a whole new document.

Saving time saves money. It frees up time for higher-paid experts to lend their expertise to other priorities.

As a result of the editing performed before the first meeting—or even the development of the document for the team’s review—and the writer’s work between meetings, your team may be able to finish its review in fewer meetings, thus reducing the cost of a roomful of experts.

Trusting your document to a professional in both technical writing and editing will result in a quality document.

A quality document is easier to read, easier to understand, and easier to use as a ready reference.

It helps keep an organization informed and working together with the same understandings and processes. And producing a quality document reflects well on everyone involved in its development.