Don't Make These Common Technical Writing Mistakes
Last month I was editing a large report which had about 700 commas. And me, THE COMMA QUEEN, deleted 2/3rds of them. There were commas between the introductory phrase, the noun, and the rest of the sentence. I love a good oxford comma (greeeeat music video by the way) but we had hanging fragments!
People are often surprised when I tell them I do more writing than math. But it’s true. All calcs have inherent assumptions which have to be recorded in the basis of design report, technical memorandums, or emails. There are moments when I’m re-arranging sentence construction for readability and I wonder how I got through 4 years at university without a single writing class.
As project manager for this project, I try not to do editing. I am generally reading with an eye to how the client will understand it, how to articulate to non-engineer audiences, and how to make language or topics clearer. Sometimes the technical part of the sentence is not the most important part. Even in a technical document.
Don’t Make These 20 Writing Mistakes
The biggest mistake is what I call word salad. There are lots of big words but they do not mean much to the reader. Recently I read a geology report that had a sentence about the different types of glaciated deposits. Nothing else in the report mentioned this and there was no context for what that is supposed to mean to the reader, what glaciation means, or how it interacts with anything else in the report. My comment to the author was “If we need this sentence, let’s explain glaciation and connect it back to the context.” We ended up deleting it.
Which brings me to my next point: sentences you don't need to keep. Sometimes we feel that adding technical bits and bobs makes it sound more professional. Or we just get really into it and enthusiastically describe everything we know about the topic. However it is distracting if it isn’t referenced elsewhere in the report or does not give the reader a better understanding so they can follow the conclusions better. Just delete it. The tip here is to keep the audience’s frame of reference in mind. Pretend to know only what they know about the topic as you are reviewing it. I often say “what did they show up to find out?”
Grammar mistakes:
Uses commas everywhere. In general, people use lots of commas,, and such. My advice is that commas for inflection of voice don't need to be there unless the sentence is confusing without it.
Commas at the end of a phase followed by and. If the rest of the phrase can be read as a complete sentence (ex. Yadda yadda yadda, and the results showed that a positive means….) then the comma is needed. If that phrase can't stand alone then nix the comma.
Apostrophes everywhere but especially after plural acronyms (ex. The vibrating wire piezometers or VWPs are placed…). Possessive acronyms would still get one (ex. The VWP’s cord shall be 150 ft….).
Semi-colons, when not used for lists, should be followed by an entire standalone sentence; make sure it is not a fragment (ex. this sentence).
Two spaces after sentences. This is one that really polarizes people. They love the two spaces. This was officially changed from our old typewriter en quad to a single space in the 90s. It is better for our digital future (aka things found on webpages and code) so we might as well get into the habit.
Describing something that would be better disseminated as a table.
Or a visual.
Not adhering to brand policy. This could be your personal brand or your company brand. Some of it is simple like the rule on one space after sentences. Some is more complex. For example a Jacobs brand policy is to write in a way that is understandable and technical but does not talk down to the audience. We have a whole guide on this.
Ending a sentence on a preposition. (Bad ex. see last sentence above). Some prepositions are on a mission (apparently) but basically it’s a word that describes place, time or position.
Being too chatty. Sometimes when I get reports from technologists it will have, if the technologist has had their extra coffee today, commas and injunctions in the middle of a sentence (bad ex. see this sentence). It's a side thought in the middle of a thought which is distracting to your audience.
Too much data. My boss calls this "data and not intelligence". Sum up the conclusions not just the data or analyses. Know if your audience is very analytical-brained or not. Some of them may need this to feel like they’ve gotten the point. Your job as the writer is to help even the analytical types be able to describe your work to a non-analytical type.
Reads like a chapter book. For anything other than a PhD thesis, you’ll want to put all the information up front and then reiterate as you go. I did a whole post on audience-based presentations. The same is true for writing. Do not talk about your material in a linear progression in which you worked on it. You'll have to do the extra step to think of it by topics and not chronological time.
Not checking the references. Too many times a writer will use a reference they know very well so they don’t actually put it in the Works Cited section. If it is referenced it needs to appear as a whole reference someone can find. I also require that my teams copy/link that published article into a References folder so that any of us can refer back to the actual article.
Appendices, tables or figures that are out of order. The first table that you refer to in the text should be Table 1. The first appendix referred to should be Appendix A. To eliminate a mistake, I tend to name all Appendices ‘X’ until the text has been written. Also, tables always go before figures.
Inconsistency. If you have dates or numbers (Jan 10, 2020 or January 2020) then they should be consistent in their formatting throughout the entire report. (Bad ex. This 1 is an important one or at least the top ten (10).) Same with use of units that can be spelled or symbolized in different ways.
The use of conditional tense. Engineers can be squirmy sometimes. Did you likely find or did you find based on the information you had? Our jobs as engineers means we have to stand by what we do because we have an ethical obligation to the profession. It's okay in some places to be delicate about the information but we should recognize that taking risks is part of the business. Manage the risk and if you’re not sure the bigger risk profile, that’s when you should connect with the PM or others on the messaging.
Section references that are unlinked. Inevitably your headings and section numbers will change so if you link it (similar to how you would add an URL) then it will change as well.
Extra words that don’t add context. Like saying something is fairly similar. What is the difference between fairly similar and similar?
Passive sentences. An active sentence structure is generally easier to read for the audience. Active sentences come in the form "A did B." Passive sentences, however, come in the form "B was done to A." Flip them around so they are active.
Complicated lists. Lists that get complicated should use a ; to separate the items. You may even start with a : to let your audience know that the items are a list. If you opt for using bullets for your list, end the last one with a period.
The words fewer/less used interchangeably. I have a friend that corrects my misuse of this irl (and yes, it’s super annoying). If it is a countable integer then use the word ‘fewer’. (Ex. This checkout line is for 15 items or fewer). If you can’t count it, then you can use the word ‘less’. (Ex. Less talk and more work!)
Hopefully these helped. These are the ones that jump out at me when I’m reviewing others’ work. Mistakes in grammar and writing can take away from the credibility of the author. It’s a good idea to go back and see what the editor changed so that you are always learning and improving your writing skills.
Got any I missed? Let me know in the comments!
—————————
Listening: Robert Earl Keen live at the Majestic Theater in San Antonio. Here’s a good one.
Working: We started up some construction on site. I’ve been going back and forth between my home office and the site office to make sure that everything runs smoothly.
Watching: I watched Wildlife with Carey Mulligan and Jake Jyllenhaal. It’s a drama and real heavy but def worth it. I also rewatched Gone in 60 Seconds and it was hilariously bad.