Tag: Technical Writing

Raise your hand if you have ever heard of Strunk and White’s “The Elements of Style.”

Now, raise your hand if you’ve ever used Strunk and White’s “The Elements of Style.”

Finally, if you raised your hand on the second question, raise it if you have used it lately.

Had the above commands been presented to me before I was given this blog topic, my hand would have remained firmly at my side. I have been a technical writer for more than 30 years. I’ve used “The Associated Press (AP) Stylebook,” the “Government Publishing Office (GPO) StyleManual,” and “The Chicago Manual of Style.”  But Strunk and White (as I found it’s commonly called)???

I’m pleased to say that in completing this assignment, I discovered a gem. And, in case you’re not familiar with Strunk and White or have forgotten its worth, I will tell you what I found.

Who Is Strunk, Who Is White, and How Did this Book Come About?

More than a century ago, William Strunk was an English professor at Cornell University. In 1919, he wrote a 43-page style guide and published it solely for use at the university. He called it “The Elements of Style.”

One of Strunk’s students was E.B. White. In 1927, White became a daily contributor to The New Yorker magazine, and he later wrote the well-known children’s books “Stuart Little,” “Charlotte’s Web,” and “The Trumpet of the Swan.”

In 1957, thirty-eight years after having been Professor Strunk’s student, E.B. White rediscovered the little style. Strunk was deceased, but with the original publisher’s permission, White edited and expanded Strunk’s textbook.

The book has been revised three times (twice by White), and the fourth edition (2005) contains minimal changes, a new foreword by E.B. White’s stepson, and a glossary of grammatical terms. Since its publication in 1957, more than 10 million copies have been sold. To date, it has almost 7,000 reviewers on Amazon who have collectively given it a 4.6 out of 5. So perhaps those of us who have not heard of it are just late to the party, but let’s jump in.

Seven Helpful Aspects of the Book and How It is Written

1. It is 96 pages long.

Imagine having to read all 1,146 pages of the 17^th edition of “The Chicago Manual of Style.” Just navigating the hardcover version is cumbersome!

The “AP Stylebook” is just over half as long, but it makes me yawn just to think about reading it cover to cover.

But “The Elements of Style” is short and easy to read. And it’s not boring—but more about that later.

2. The style is simple, repetitive, and clear.

First, it states the rule. Then, it gives examples of how the rule can be used to improve or correct a sentence or group of words. If there are notable exceptions to the rule, they are provided.

Rule 19, “Express coordinate ideas in similar form,” provides a sampling of the many examples that are provided throughout the book.

Rule 19 emphasizes that “. . . the writer should follow the principle of parallel construction.”

The next directive about parallel construction states:

Some words require a particular preposition in certain idiomatic uses. When such words are joined in a compound construction, all the appropriate prepositions must be included, unless they are the same.

Then:

Correlative expressions should be followed by the same grammatical construction. Many violations of this rule can be corrected by rearranging the sentence.

Perhaps you would have successfully corrected or improved each of the above, but the examples themselves show how one rule, “Express coordinate ideas in similar form,” has included several related rules and provided clear and compelling examples.

3. The explanations are succinct.

Here are but two of an entire book full of concise, easy to grasp explanations:

A dash is a mark of separation stronger than a comma, less formal than a colon, and more relaxed than parentheses.

Prefer the specific to the general, the definite to the vague, the concrete to the abstract.

4. You can take notes, underline, and easily find things again.

Both the book’s brevity and its organization are helpful in being able to use your highlighting or underlining to easily find things again. It’s especially handy to have it on an e-book reader where you can highlight passages and copy and paste sentences into a Note. Then, you can use the table of contents, your notes, and your highlighting to quickly find what you need.

5. It’s readable because it’s expository rather than encyclopedic.

The book “talks” to the reader. It’s not a mere listing; it’s a commentary. It’s as though your 9^th grade English teacher is explaining something to you (only funnier—but we’ll get to that one, too).

Rule 3 in Chapter 1 states simply, “Enclose parenthetic expressions between commas.” Then the writer admits:

This rule is difficult to apply; it is frequently hard to decide whether a single word, such as “however,” or a brief phrase is or is not parenthetic. If the interruption to the flow is slight, the commas may be safely omitted. But whether the interruption is slight or considerable, never omit one comma and leave the other. There is no defense for such punctuation as

Marjorie’s husband, Colonel Nelson paid us a visit yesterday.

Imagine the words “there is no defense for” in the AP Stylebook. But that is one reason you can enjoy and remember the explanations.

6. The voice is emphatic.

There’s nothing wishy-washy about the language in this book. When the writer (whether Strunk or White) is disdainful of certain constructions, it is clear. When it’s important that you understand, the writer makes sure his point hits home. When something is poorly worded, there’s always an example of how it can be fixed, but there is also an explanation of why it’s poorly worded or what effect it has on the reader.

For example, the commentary about the word “certainly” in the chapter called “Words and Expressions Commonly Misused” minces no words:

Certainly. Used indiscriminately by some speakers, much as others use very, in an attempt to intensify any and every statement. A mannerism of this kind, bad in speech, is even worse in writing.

Is there any doubt about the writer’s opinion of “certainly”?

7. The content is simply and logically divided.

Chapter 1: Elementary Rules of Usage – 11 Rules.

Chapter 2: Elementary Principles of Composition – 11 Rules.

Chapter 3: A Few Matters of Form – 11 short sections, beginning with a single plural noun such as “Colloquialisms,” “Headings,” “Numerals,” “Parentheses,” and “References.”

Chapter 4: Words and Expressions Commonly Misused – 121 usage errors, including misused words, words that are not interchangeable but often confused, and word endings. Some of these may trip up even experienced writers. Each is explained in one paragraph, and, in some cases, it is accompanied by an example or two as well.

Chapter 5: An Approach to Style (With a list of Reminders) – 21 reminders to help the reader create narrative writing that is tight, clear, effective, and unpretentious.

My Reactions, Some Things I Learned, and Things That Are Good To Review

Eight of My Reactions

1. Humility – I knew there were things I had to look up from time to time (besides technical terms and whether to add trademarks, registration symbols, etc.), but I was confident I was close to knowing it all. Well, Strunk and White proved me wrong. I had more than one revelation that caused me to think, “Whoops! I’ve done that incorrectly.” And there were several times that I thought, “Have I been doing that correctly?” And there were even times that I thought, “I’ve never heard that one before.”

2. Satisfaction and Appreciation – Mixed in with the humbling content, there were things in which I took satisfaction in having known and adhered to. There were things that made me thankful to have had Ms. Blocker for 9^th grade English. It was good to remember her diagramming sentences on the board, how emphatically she spoke, and how desperately she wanted her teaching to stick. I wish I could write her a note and tell her that it did.

3. Amazement – How can so much be packed so tightly? By page 45, I thought, “Is there anything about writing and grammar that’s not in here?

4. Realization (perhaps better communicated by “duh”) – I encountered things that I thought I had been doing intuitively. Strunk and White showed me that I was not so intuitive after all. “Oh,” I had to admit to myself, “there’s a rule and a reason for that. I just forgot and attributed it to my fine ear and logical mind.”

For example, Chapter 4, “Words and Expressions Commonly Misused,” addresses the use of these words:

Among. Between. When more than two things or persons are involved, “among” is usually called for: “The money was divided among the four players.” When, however, more than two are involved but each is considered individually, “between” is preferred: “an agreement between the six heirs.”

Had I been asked to fill the correct preposition in the preceding examples, I would have answered correctly. But I had forgotten or not understood the distinction to be “but each is considered individually.”

5. Surprise and Recognition – “Wow! How long has it been since I thought about that? Makes sense, though.” Here is one of the instances that took me back. Doubtless you will find others.

Rule 15, “Put statements in positive form,” provides three examples of improving a sentence by removing “not” and rewording the sentence. The writer than explains:

All three examples show the weakness inherent in “the word not. Consciously or unconsciously, the reader is dissatisfied with being told only what is not; the reader wishes to be told what is.

My reaction was, “How long has it been since I spent time thinking about the word ‘not’?” I must admit, however, it makes perfect sense.

6. Wondering About Overthinking – This made me realize that some things I’ve been overthinking or spending too much time to improve are fine the way they are. What a relief!

The idea of the word “none” being followed by a singular verb has been indelibly etched in my brain. In Rule 9, “The number of the subject determines the number of the verb,” I sailed right through using a singular verb after each, either, everyone, everybody, neither, nobody, and someone. I continued to congratulate myself in knowing:

But then I encountered this:

A plural verb is commonly used when “none” suggests more than one thing or person.

“None are so fallible as those who are sure they’re right,”

Would I have worked at that sentence worrying that I should change the whole sentence so that it could rightly use “None is”? Would I have shrugged and said, “Well, it kind of sounds right . . .” Would I have overthought something that was already correct? Now, thanks to the writer having offered it as the exception, I don’t have to worry about it.

7- Enthusiasm – Sometimes Strunk and White simply elicits a “Yes! I wish other people could be convinced of that!” By the way, Strunk and White warns against overuse of the exclamation point, but I really am excited when I write that, and you’ll see why in a minute. Here’s what Strunk and White says:

Do not attempt to emphasize simple statements by using a mark of exclamation. The explanation mark is to be reserved for use after true exclamations or commands.

As it turns out, my sentences match the examples that are provided.

Every day, I read or hear a journalist misuse the English language. Yesterday, I read an article about a wedding. The bride died shortly before the wedding, and the families decided that the groom should marry the sister of the bride. The article began with:

“In a series of unfortunate events, a groom married the sister of his bride after she collapsed and died earlier in the wedding ceremony.”

Rule 20 of Chapter 2, “Elementary Principles of Composition,” says:

The position of the words in a sentence is the principal means of showing their relationship. Confusion and ambiguity result when words are badly placed. The writer must, therefore, bring together the words and groups of words that are related in thought and keep apart those that are not so related.

Then it provides four rules for avoiding ambiguity. Each rule is followed by an explanation and examples of awkward construction and how to improve them.

Yesterday, I also came across an article that said an endeavor “failed bigly.”

Here’s what Strunk and White has to say:

Do not construct awkward adverbs. Adverbs are easy to build. Take an adjective or a participle, add -ly, and behold! You have an adverb. But you’d probably be better off without it. … Words that are not used orally are seldom the ones to put on paper. Do not dress up words by adding -ly to them, as though putting a hat on a horse.”

And how many times have you heard, “Sadly, he passed away” or “Hopefully, the victim will survive.”

Here what Strunk and White says about “hopefully:”

This once-useful adverb meaning “with hope” has been distorted and is widely used to mean “I hope” or “it is to be hoped.” Such use is not merely wrong, it is silly. To say, “Hopefully I’ll leave on the noon plane” is to talk nonsense. Do you mean you’ll leave on the noon plane in a hopeful frame of mind? Or do you mean you hope you’ll leave on the noon plane? Whichever you mean, you haven’t said it clearly.

Now you see why I delight in saying “Yes!” and why I wish others were convinced of these blunders.

8- Pure Enjoyment – This book is short, engaging, emphatic, and sometimes an example is such a perfect distillation of the subject that you may stop, back up, and read it again. But there also some passages of unadulterated disdain that made me chuckle:

The foreseeable future. A cliché, and a fuzzy one. How much of the future is foreseeable? Ten minutes? Ten years? Any of it? By whom is it foreseeable? Seers? Experts? Everybody?

In Chapter 4, “Words and Expressions Commonly Misused,” there is a discussion of the word “people” that includes this warning:

The word “people” is best not used with words of number in place of “persons.” If, of six people, five went away, how many people would be left? Answer: one people.

Things That I Learned

Perhaps the sentences in this section will provide examples of little-known rules. Perhaps they will only serve to reveal the blog writer’s ignorance. But I am given some indication that I am not alone when I highlight a passage and my e-reader lets me know that 680 other people have highlighted the passage:

It is permissible to make an emphatic word or expression serve the purpose of a sentence and to punctuate it accordingly.

Again and again he called. No reply.

The preceding example is not one that a technical writer is likely to incorporate, but it was interesting. I knew it was employed in literature, but I didn’t know it was “correct.”

Rule 10, “Use the Proper Case of Pronoun,” contained this short gem:

Do you mind me asking a question?

Do you mind my asking a question?

In the first sentence, the queried objection is to me, as opposed to other members of the group, asking a question. In the second example, the issue is whether a question may be asked at all.

Again, I would have correctly identified the correct usage, but the example provided new insight.

I learned something from the paragraph below, as I thought “to” always followed compare in instances like these:

Compare. To compare to is to point out or imply resemblances between objects regarded as essentially of a different order; to compare with is mainly to point out differences between objects regarded as essentially of the same order. Thus, life has been compared to a pilgrimage, to a drama, to a battle; Congress may be compared with the British Parliament. Paris has been compared to ancient Athens; it may be compared with modern London.

Here are two more I’ve misused:

Enormity. Use only in the sense of “monstrous wickedness.” Misleading, if not wrong, when used to express bigness.

Claim. (verb). With object-noun, means “lay claim to.” May be used with a dependent clause if this sense is clearly intended: “She claimed that she was the sole heir.” (But even here claimed to be would be better.) Not to be used as a substitute for declare, maintain, or charge.

Things That are Good to Review

Here are some things the book offers that are worth your review.

1. Never forget structure.

Rule 12 in Chapter 2 is “Choose a suitable design and hold to it.”

A basic structural design underlies every kind of writing. Writers will in part follow this design, in part deviate from it, according to their skills, their needs, and the unexpected events that accompany the act of composition. Writing, to be effective, must follow closely the thoughts of the writer, but not necessarily in the order in which those thoughts occur. This calls for a scheme of procedure.

2. Don’t get sloppy. Keep your editing fierce.

Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all sentences short or avoid all detail and treat subjects only in outline.”

3. Appreciate brevity and review the techniques to achieve it.

The habitual use of the active voice, however, makes for forcible writing. Many a tame sentence of description or exposition can be made lively and emphatic by substituting a transitive in the active voice for some such perfunctory expression as “there is” or “could be heard.”

The writer then adds:

Note, in the examples above, that when a sentence is made stronger, it usually becomes shorter. Thus, brevity is a by-product of vigor.

Conclusion

Simone Biles, 24, has won a combined total of 32 Olympic and World Championship medals, making her America’s most decorated gymnast. Biles began gymnastics training when she was six years old. With 20 years of training and 32 medals, why does she need a coach?

The answer is simple. She needs critique and encouragement. Just as critique and encouragement keep Biles at peak performance, it can keep an experienced writer from lapsing into complacency.

Reading Strunk and White’s “The Elements of Style” combats complacency and replaces it with humility and determination. Using it for reference can provide constant encouragement. Precision can be mastered!

You may now feel like you have read dozens of reviews on a bookseller’s website. However, I hope you learned something more than the reviewer’s opinion of the book. I hope you learned something from the book itself.

And I hope you got a flavor of why it is a valuable companion reference for meticulous writers who, like those employed by The Writers For Hire, insist on precision in pursuing their craft.

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.

Barbara Adams is an award-winning writer with more than 30 years of technical writing experience. Her portfolio includes hundreds of whitepapers, case studies, trade articles, op-eds, books, and brochures. And at TWFH, Barb is our go-to authority for all things technical.

For this installment of Copywriter Q&A, Barb talked to us about the art of making technical content accessible to a broad audience.

TWFH: What is the biggest issue with content that is too technically written?

Unless you’re writing a textbook and you can assume everyone has taken the prerequisite courses and is speaking the same “language,” the risk of making an article, case study, or even a white paper too technical is that you will lose readers.

People read with their self-interest in mind, and if they don’t feel they’re getting information they can use – or they have to work too hard to get it – they’ll tune out.

I write a lot of articles for a client who develops simulation software – the most high-level technical products I’ve ever written about. And even though readers are design engineers, they are specialized, and I can’t make assumptions about what they know.

Not everyone works with fluid dynamics, for example, so I have to explain it, without insulting anyone’s intelligence.

TWFH: What are some examples of situations when content should be simplified for a broader audience?

Marketing pieces are a good example of when content needs to be simplified.

You don’t need to know how to make a watch to tell time. But, as I mentioned, even technical white papers can benefit from a little explanation of terms.

It’s wrong to assume everyone knows as much as the author who did the work or experiment does. 

TWFH: Is there a way to “dumb it down” without losing the intended message?

I’m not a fan of the expression “dumb it down,” but I understand what you’re asking.

Translating a highly technical piece to a consumer audience is probably the only place where we’d have to make the language super simple and focus more on what happens because of technology —the benefits —rather than explain in great detail how the technology works.

TWFH: What are some ways to simplify language so that a broader audience will understand it?

I’m a big fan of analogies rather than simplifying language. Technical things are called what they are called – I’m not sure there’s a way to simplify the words “calculating the fluid forces on the wave-forming device,” which is something I wrote about, but you can provide an analogy.

People understand that when they put their hand in a container of water, the water will move and how much it moves depends on how hard they push their hand down.

TWFH: When writing technical content for a non-technical audience, should unfamiliar terms be defined? Or is it better to just stick with terms that are not so technical?

That is an excellent question. I would vote for using technical terms and defining them. The client will be communicating with the audience multiple times, I imagine, and if you start introducing non-technical terms, you have to remember them and what they meant and why you used them.

As a parallel, consider lying versus telling the truth. If you tell the truth, you just have to remember what happened. If you lie, you have to remember what really happened and then what you said happened, and that’s a lot more difficult.  Heady stuff, right?

TWFH: Do you suggest integrating visuals with technical instruction to help illustrate concepts?

Yes! But then make sure the cutline (or caption) explains what the reader is looking at.

A white paper cutline that says, “The model of the experiment,” isn’t as useful as one that says, “The experiment did A, which resulted in B.”

TWFH: This is all wonderful information! Do you have any other tricks or tips for making technical content more accessible?

Organizations are often siloed – one group doesn’t necessarily know what another is doing, or they have expertise about a topic that is housed in just one department.

If a client and I are trying to work out whether the content is accessible or not, I might suggest they run an early draft by a counterpart in a different department. It never hurts to have another set of eyes on your copy.

When it comes to adding clout to a piece of writing, fewer things help more than talking to a subject matter expert (SME). They know the ins and outs of what you’re writing about and they know it well. They are the expert after all.

The context and technical knowledge that an SME brings to a piece of writing is undeniable. The journalism world is effectively built on that principle. It’s hard to find a story in the newspaper that doesn’t contain at least one expert’s words on the matter, and for good reason. Imagine how ineffective a piece about the economy would be without a quote or two from someone who spends their lives living and breathing economics?

But, getting the information out of them can be a challenge sometimes. SMEs, whether they know it or not, take a lot of what they know for granted. They’ve immersed themselves in that world for so long that they forget that not everyone has that same level of knowledge.

This can make interviewing them hard. They can end up providing answers to questions that aren’t helpful, or they don’t go into enough detail. It becomes a situation where you end up feeling frustrated by the responses or, worse, the SME starts feeling like their time is being wasted.

All is not lost, though. While sometimes the problem stems from the SME just not knowing how to get out of their head, a lot of the time it’s just a matter of not running a tight interview. Being unprepared or asking questions that don’t guide the conversation in the right direction can hinder your ability to have a good interview with an SME.

When handled properly, SMEs are highly engaging and full of useful information. The following tips will help you get the most of out your conversation with an SME.

Preparing for the interview

This stage is probably the most critical stage of the interview because the trick to getting the most out of an SME is to know how to run a good interview.

This goes beyond just asking good questions. It’s about making sure that you don’t waste the SME’s time. It’s keeping the interview on track, so you don’t end up miles away from the topic you’re writing about. And, yes. It’s also about asking good questions.

The first thing you should do is be prepared.

• Make sure you’ve got your questions ready to go. Have them written down and organized in such a way that there’s something of a natural flow to the conversation. This isn’t always possible, but the goal is to make the interview feel more like a true conversation, more than an interview. This helps the SME feel a little more relaxed about being interviewed.
  
  
• Make sure all the technical equipment you’re using is working. This includes any video conferencing services you’re using, recording devices,  right down to your pens. Everyone knows that things go wrong from time to time, but sometimes SMEs only have a specific amount of time to dedicate to helping you out and time spent dealing with technical issues cuts into their time.

• Be early. This is good for a couple of reasons. The first is that if you’re meeting in person, it gives you time to get ready after getting there. It’s normal to get somewhere and feel slightly disorganized about everything after even a short car ride. Allowing yourself an extra few minutes to get organized goes a long way. The same with online meetings or phone calls. Be ready ahead of time. Jump into the conference room early to make sure it’s working. Test the recording device. Make sure nothing is wonky. Every little bit helps when it comes to running a solid interview.
  
  It also helps to provide as much context about the interview to the SME ahead of time, as possible. You want them to be thinking about what they’re going to say, without going so far as to provide the questions. This helps them focus on off-the-cuff responses to your questions, which are often way more helpful than the answers you get when you send the questions ahead of time.
  
  
• Record the interview and take notes. A recording is your way to go back and revisit the conversation to pull out all the details that you may be fuzzy on. Note-taking is often your backup. Recordings fail. Things go wrong. The last thing you really want to do is go back and ask about a redo. So, take notes. Not only does this help when a recording fails, but note taking also allows you to create silence. Silence makes people uncomfortable and, as a result, they start talking.
  
  This is when the SME often takes a moment to expand on what they just said, going deeper into the material and following up with details that you probably wouldn’t have otherwise come up. Take a moment the first time it happens to explain that you’re taking notes, then let the silence hang in the air, while you wait for the SME to fill the space with valuable information.

Once things get started

When it’s time to get the interview going, start things off with a bit of small talk. Nothing too deep. Something as simple as, “How’s your day going so far?” is often enough. The point isn’t to have a big, deep conversation about life, but to be friendly enough to soften things up and put the SME at ease. You want this to feel more like a conversation than a job interview.

Remind the SME that you’re not going to be taking up all their time. You’ve got a specific amount of time blocked out for the interview. You can also mention that you’re going to do your best to wrap this up early. This means you’re going to have to keep the conversation on track, but that’s okay. You don’t need to know everything the SME has to say, you just want the bits that are relevant to your topic. If you find the interview drifting off-topic, wait for a pause, then say something like, “So thinking back to…” and ask another question about your topic.

In this stage, you have two main goals: listening and guiding the conversation. You need to listen more than you talk, but the trick isn’t just to be quiet and take notes. It’s to listen for those juicy nuggets of information that make you raise your eyebrows and say, “Cool!” These details are the whole reason you’re having a conversation with the SME. It’s the stuff that doesn’t come up in research. It’s the stuff that helps transform writing from something mediocre into something that informs people on an expert level.

Best of all, you use this stuff to guide the conversation into uncharted territory by listening for those details and asking questions around it.

Asking good questions

Outside of listening, asking good questions is the most important part of talking to SMEs. You want the information that’s inside their heads—the good stuff that they take for granted as common knowledge. Sometimes getting that knowledge out in a way that is understood can be tricky.

SMEs are used to talking to their peers about what they do. They use a lot of jargon. They gloss over certain bits they assume everyone knows. And, sometimes they just aren’t comfortable talking to people, even though they agreed to do the interview. Luckily, good questions can help solve all these problems.

Ask questions that spark interest in your SME and get them talking about the thing they’re passionate about. These questions will vary depending on the kind of writing that you’re doing, but there are some guidelines that you should follow.  

• Ask opened ended questions. You’re not going to get anywhere if you ask your SME questions that have yes and no answers. They don’t help guide the conversation at all.
• Ask why a lot. This question is so helpful that a whole process was developed around it. The 5 Whys works because it drills down into the heart of the problem. By constantly asking the question “Why…” you force the SME to explain to think a little bit more about the process they used and why they made the decisions that they did. It’s really helpful at getting more than just a superficial response to your question. Often, after the fifth why, you’ve hit the heart of the problem
• Don’t be afraid to ask basic questions. They can be a good way to get an SME warmed up for the more in-depth questions. Something simple like, “Tell me a little bit about who you are and what you do?”
• Don’t be afraid to ask “stupid” questions. The SME is the expert, not you. If you don’t understand something, ask about it, no matter how silly the question may seem. Among other things, if you have those questions, chances are someone else will as well. So ask away.

Sample questions to get things started

When you ask a question, be sure to frame it in relation to the topic. The more specific you are when asking the question, the better. When you start off, asking something like, “What made you do this?” seems like a good question, but phrasing it like this will likely provide a better answer: “What problem were you trying to solve by doing this?” This can be followed up with something like, “Why was this a problem that needed solving?” And so on.

Remember, SMEs don’t typically think about the process they use, they just do the work. You want them to walk you through their solution as thoroughly as possible. Once they’ve answered the question, move them on the next one.

Every interview is going to be different, so the exact questions you ask are going to vary from person to person. Of course, having a list of questions that you can pull from can help get things moving when you’re planning out your interview.

Here are some ideas:

• How does that happen? 
• What makes that happen? 
• Why does that happen?
• If that doesn’t go wrong, what happens?
• Can you explain what you mean by that?
• What challenges did you encounter while doing X?
• What surprises did you encounter along the way?
• What’s next?
• How have people responded to X?
• What makes this sexy?
• What are the common mistakes that people make in this area?
• What are some of the areas that cause the most confusion?
• What are some of the most common questions you get about this topic?
• What’s one question that nobody ever asks you, but should?
• Is there anything that I should have asked you today, but didn’t?

Once you’ve started asking your questions it’s time to stay quiet and let the SME do the talking. The only time you should interject is to ask for clarity on something that’s been said.

If your SME isn’t talking or isn’t being super cooperative, don’t fret. This happens. One way to kick start things is to ask if there’s anyone else they can think of you could talk to. This question can sometimes snap someone out of their head a little and make them realize that they’re not being as helpful as they could be.  

A few things to avoid doing

This will be short and sweet.

• Don’t be late.
• Don’t talk more than the SME.
• Don’t talk over the SME.
• Don’t let the interview run too long.

Once it’s over

Thank the SME for their time. Ask them if you can follow up if you find you missed a question, or something needs more explaining. And offer to send them the piece once it’s done. And, again, thank them for their time. You want them to know you really appreciated their help.

That’s it. The biggest challenge that you’re likely to face with an SME is getting them to talk. SMEs love what they do and they love talking about what they do. All you have to do is the right questions.