Wilson & Associates Monthly Newsletter, March 2017
What do Technical Writers Do?
By Laura Kilgore
Technical writing, contrary to popular assumption, is not a one-dimensional role. When I first became a Technical Writer, I pictured myself poring over hard-copy documents, red pen in hand, making good use of the secret hieroglyphics of Editors that I had learned so proudly in college. Green eyeshades and a clacking printing press may have also been featured in my imagination, but I was a bit idealistic. Yes, I do always print out the draft I get of a new document, and there is something empowering (and self-validating) about filling in the margins with notes and adding my proofreading marks to the lines of text, but really, this is only a fraction of a Technical Writer’s role.
So what do we do?
Know the content
I was surprised to find, in my first freelance project in the aerospace industry, that a good Editor does not need to understand the content of a document in order to effectively edit it. Any skilled Technical Writer can tell instinctively if a sentence is grammatically correct. I wasn’t going to learn enough rocket science to catch the full meaning of the document, but, over time, the ideas in the text did become more familiar.
That being said, it is better to know the content, and a good Technical Writer will make the effort. I will always pick up on more and deeper problems in a document when I understand what I’m reading. One of the first things I learned when I started working with engineers is that they enjoy explaining their subject. Since then, many a word-smithing session has transformed into a useful lesson, complete with dry-erase diagrams and a plethora of information.
There have also been times when I turned to Google for information. “Christmas Tree” was high on the list of confusing terms in the oil and gas industry, but brainstorming sessions with authors took on a whole new meaning when I discovered exactly what it was. My eyes were further opened when I saw a real-life Christmas Tree or ‘X-tree’ in Wiess Energy Hall at the Houston Museum of Natural Science. So while it’s not absolutely necessary to be an expert in the topic, Technical Writers do make a concerted effort to understand the basics.
Edit the content
And then, of course, there’s the actual editing.
But this isn’t just a quick read-through with that red pen. I like to review a document three times, using a ‘high-low-high’ method, before I’m happy sending it back to the author. The first review is a quick and very basic one, during which I make sure the document is in the correct template and I skim it for glaring mistakes.
The second review is where I print it out and tackle the nitty gritty. I read every word, check every punctuation mark, and verify the completion and clarity of every sentence. The third reading goes back to a high level where I consider the organization of the content and make sure the table of contents is updated.
After the high-low-high initial edit, comes several low-level edits that I make between passing the document back and forth to the Author, reviewers, and approvers. The final review is, perhaps, the most important. This is when I remove the draft watermark, read through the document one more time, and, again, update the table of contents and all cross-references. Only then can I send it to the document authority with confidence.
Throughout this process, the Technical Writer is always careful not to alter the meaning of the content or any engineering data (pressures, pipe sizes, etc). If the content needs to be clarified, I’ll work with the Author to rephrase as needed.
Control the document
Technical Writers are also responsible for maintaining the integrity of the content in the document, tracking each change and who is making them. This requires keeping a close watch on the content and keeping records of everything.
Throughout the process, I communicate with all those who have access to the MS Word version, whoever is currently holding the latest version, and those who are permitted to make changes to it. This is to make sure the project is moving forward and to prevent different people working on it at the same time (SharePoint also helps with this).
In my current position, when sending a document out for review, we send either a PDF of the document and what we call a ‘comment tracker’ MS Excel spreadsheet or a protected MS Word version with a clear request that the reviewer use the ‘Track Changes’ feature. Where reviewers do not track their changes, we have tools like SharePoint to assist with comparing and recording versions.
Manage the project
Because we are in charge of document control, much of the document development process also depends on the Technical Writer. Whether or not my team has project managers, there is always an aspect of management that will fall on me. Technical Writers track the progress of our documents, assist with meeting project milestones, set up meetings, make sure all necessary parties are in the loop, and generally shepherd the review process. This aspect of the Technical Writer role requires strong personal organization and communication skills.
Document review meetings are essential to the document development process, It is during these meetings that stakeholder feedback can be discussed and incorporated into the document. Technical Writers drive and facilitate these meetings, which sometimes include off-site participants and require the use of remote communication software. During these meetings, we share our computer screens with the participants, displaying an MS Word version or Excel spreadsheet containing the document and edit it in real-time, based on the discussion.
Before these meetings, the Technical Writer prepares the meeting materials and verifies that attendees are familiar with the content and organization of the document. We must also have good verbal communication skills, both with participants in the room and those calling in from around the globe.
Know the software
MS Word is a staple in the document development world, which makes it essential for Technical Writers to know it thoroughly. We can’t live without it. It has its glitches, but the more I work with it the more ways I’m learning to get around them. It has a huge number of features that we must be able to navigate successfully.
Most document development teams also use some sort of collaboration software, like SharePoint, where they can store, edit, and share their documents. I have been expected, not only to use these applications, but also to build and maintain team and company-wide libraries with current documents. Of course there are other applications we use like MS Excel, PowerPoint, Outlook, Lync, etc., which are handy to have at least an intermediate knowledge of.
Provide training on software
Whatever my software skill level, people are going to assume that I am the person most knowledgeable about MS Word and any other program my team is using. They expect me to provide as much technical support as writing support. Whether I’m sitting in a meeting explaining text style usage in MS Word, or writing a quick-reference guide on how to access a SharePoint library, there are plenty of good opportunities to hone my teaching skills.
Along with these major responsibilities are dozens of lesser ones that we perform every day. Technical Writers have broad skill sets, and we are always challenged to expand them. We’re here to support our authors, our teams, and our fellow Technical Writers in whatever capacity we’re needed and to do it to the best of our ability.
By: Bonnie Bryan Denham
As a Technical Editor that’s spent 4 years in the aerospace industry and 11 years in the oil and gas industry, a popular phrase I’ve gotten used to hearing is, “Work your magic.” This “magic” (mostly white magic, but sometimes involving a little black magic when MS Word is misbehaving) can encompass a lot. I should probably say, it encompasses everything.
Checking documents for spelling and grammar errors is just the beginning of what this phrase means to the teams I’ve supported over the years. To me, this magic also includes stellar customer service and a never-ending, enthusiastic willingness to help.
While writing this article I was asked to think of the most seemingly mysterious issues I’ve been asked by clients to remedy – things that don’t just involve formatting fixes. Three issues that come to mind are:
- Reducing the size of a file that started out small but has suddenly grown, to make it email-able again
- Removing stuck watermarks
- Consolidating multiple files of revisions into a master file (when reviewers didn’t use SharePoint or MS Word’s Track Changes feature)
Creating drop-down lists in Excel
Creating a drop-down list in Excel, so that someone can click the drop-down and make a selection from options in the list, is a form of Data Validation.
The Data Validation feature is found on the Data tab, in the Data Tools section of the ribbon. Once you set up your data validation, you may also want to set up a filter on that column to allow only certain selected choices to be displayed.
1. On a separate tab that is not being used, create a list of choices that you want to appear in the drop-down menu of the cell.
2. Now, go back to the main tab of your spreadsheet and select the cell where you want the drop-down of choices to appear. Click the Data tab at the top of the screen. In the Data Tools section of the ribbon, click the drop-down arrow under Data Validation. Select Data Validation, the first item in the list of available options.
3. On the Settings tab, click the drop-down arrow under Allow, and select List (see Figure 1). Make sure you check the boxes for “Ignore blank” and “In-cell drop-down.”
4. Next, click the square in the Source field (see Figure 2).
5. Navigate to the tab where you created the list of choices you want to be available in the drop-down list. Select the list with your cursor, and then click the square to the right in the Data Validation box (See Figure 3).
6. Click ok.
7. To apply the drop-down list of choices to other cells:
a. Click in the cell with the data validation
b. Mouse over the bottom-right of the cell until the crosshairs appear
c. Click down and drag it to the appropriate cells to apply the data validation
Now that you’ve set up the data validation (or drop-down list of choices), you may also want to create a Filter on the column so that you can select to only see specific rows of information based on your selection.
To do this, click on the column heading. Select the Data tab at the top of the screen and click the Filter button in the Sort & Filter section of the ribbon (See Figure 4).
This will apply the filter across all column headings. If the filter was only applied to the first column(s), you will need to delete any blank columns and then re-click the Filter button.
Now you should be able to click the drop-down at the right of the column heading cell and select one or more choices from the list to only see those specific rows of information (See Figure 5). Then, click OK.
Clear filters at any time by clicking the drop-down at the right of the column heading cell and selecting Clear Filter.
Get more Tips & Tricks in the online archive on our website as they are added with each new newsletter.