Leader driven Harmony #5: How to make your writing Crisp, Flavorful and Satisfying (Part III)

by Mack McKinney on December 31, 2010

Why should you read this post?  Because this little crash course in effective writing is the collective intelligence of thousands of people just like you.  It is a living document and benefits from ongoing improvements suggested by our students.  Their suggestions and observations, especially in the final section, make us all much better writers.

In this series we have discussed Purpose, Audience, Content and Style and how each works with the others to determine the utility and readability of any document you write.  We will close this series with a discussion of writing “Mechanics” in the form of a simple list of annoyances readers complain about most often.  If you want to make sure you never experience these annoyances again, we humbly suggest you Tweet the link to this document to your family, friends and everyone you work with.  Once they see what they are doing wrong, their writing will improve and your stress level will drop!

Mechanics

Here is a partial list of our students’ and our pet peeves, assembled through the years.  As a reader, if you find that a major aggravation is not listed here, email me at Mack@SolidThinking.org and we will consider including it in the next update.

This is a collection of the most common mistakes we have observed (and periodically been guilty of) in writing and assembling technical reports, CONOPS, proposals and other documents:

  1. Spell-Check. Failure to spell-check the final version, just before the final printing. Simple typos will lead some readers to conclude you are lazy, careless, stupid or all three.
  2. Total reliance upon a spell/grammar-check program, which will not necessarily catch improper word usage, for example the accidental use of “form” instead of “from”.  Read the document   s-l-o-w-l-y   and be certain every sentence makes sense.  And get others to read it.  Microsoft’s automated “help” features often are not of much help, especially with punctuation choices and grammar decisions.  Do not trust Bill Gates to protect your reputation.
  3. Failure to include a list of acronyms or failure to define every acronym the first time it is used.  Assume nothing about what your audience knows.  DOD (Department of Defense – – – see, we follow our own rules) workers, government and contractor, are especially guilty of this.  An example is “CONOPS” which, depending upon the agency, can mean Concept of Operations, Contingency Operations, Continuity of Operations, CONUS Operations (an acronym and an abbreviation within an acronym – “Continental United States Operations”), Continuous Operations and others.  Define it or don’t use it.
  4. Failure to define complex technical terms.  Don’t assume all readers are PhDs.
  5. Incorrect graphic/figure/table numbers. When these are manually input and another graphic/figure/table is added later, there is the ripple effect whereby every subsequent graphic, etc. must get a new number.  Instead, let the application (MS Word, Word Perfect, etc.) assign the numbers.  It precludes the ripple effect and automatically lets you later assemble a Table of Contents, List of Figures and List of Tables.
  6. Incorrect page number references in the text, making it difficult or impossible to find referenced sections.  This is usually caused when text or graphics are added somewhere in front of the page being referenced, causing the referenced section to slide onto the next page.  If sections are numbered as they should be and section sizes are less than a half-page in length, reference the section by name and number.  But if sections are large and referencing them would require the reader to search through several pages to dig out a referenced passage, cite the actual page number but double check all such citations for correctness just before publishing.  And be aware that a web-based document, especially an Adobe pdf document, may have page numbers that do not correspond to the hardcopy.
  7. Changing text color in the main body of the document.  Keep it black.
  8. Failing to italicize non-English terms (fait accompli, ad hoc, coup de grace, blitzkrieg, etc.) so people can mentally pause to remember what the term means or using the terms improperly (and we are not talking here about commonly used terms such as “via” or “vice versa”).  If you cannot pronounce a foreign term properly, or don’t know exactly what it means in the native language and how it are used in the native culture, it is probably not commonly used here in the US.  So don’t use it.  And a special caution to Francophiles (lovers of all things French):  We have found that ad nauseum – – –  Latin for “excessive to the point of causing vomiting” – – –  use of French phrases is often the hallmark of a person flaunting a writing education they never received, insinuating an intelligence they don’t actually possess or adopting a French perspective which, by itself, may upset some Americans.  Politics and cultures aside, English is a fine technical language with plenty of precise, descriptive terms.  Use them.
  9. Beginning sentences with “but” or “and”.  This is common use now.  Increasingly, people write like they speak.  It isn’t the death of English as we know it.  Get over it.
  10. Assuming that the reader can mentally keep track of where all the pieces of a CONOPS reside.  In the case of a CONOPS or proposal that has components classified at various security levels, this assumption is folly.  Give the reader a roadmap showing where all the components are, their classifications, etc.
  11. A document manager’s failure to provide a style guide and then complaining about all the work he/she must do to pull the final document together.
  12. Failure to provide references in support of key claims, instead hoping the reader just accepts the claim.  As in medicine and science, the bigger the claim, the more solid the proof needed to substantiate it.  And be certain the trip is worth it for the reader: make certain the proof you cite is directly related to the claim, not a peripheral issue!  Remember that technical professionals do not spin findings or conclusions.
  13. Failure to cross-check every text reference to a table or figure to ensure
    • The reference is correct, i.e. such a table/figure a) actually exists and b) adequately discusses the subject indicated in the text
    • The table or figure follows the reference
    • The references in the text are sequenced properly (for example Table 3-2 should be discussed in the text before Table 3-3 is discussed)
    • Any referenced document is the most current version available.  And be sure to cite the revision number and date or just use dates as revisions (rev 15 Feb 09).
  14. Reliance upon complex graphics to make a key point instead of to support a point.  Excessive use of graphics throughout the document/section is often an indication of a poor/rushed author or an unskilled writer attempting to use graphics in place of text.
  15. Misuse of the forward slash (/).  The commonly accepted meaning is “and-or”.  If you cannot substitute “and-or” then the slash is inappropriate.
  16. Beginning to write the report without an outline and letting it meander. This is often evident to even a casual reader of the resulting document.
  17. Misuse/absence of embedded links in a document.  In our web-based world, most documents are reviewed in softcopy.  So use hyperlinks to take readers to key sections and appendices. But be sure that each linked page has a “return to previous page” link so the reader can quickly return to the previous page being read.
  18. Starting the report too late and then rushing to finish. The resulting report almost always suffers with sections obviously written by different authors, key conclusions glossed-over, graphics overused and unaccompanied by explanations, typos, etc.  The typical excuse that managers hear most often is “I was too busy DOING the work and did not have time to REPORT on the work!”  My advice is not to use this excuse.  It marks you as a rookie who cannot plan his time properly.
  19. Use of vague terms like “recently”, “some” and “few”.  Quantify!  Use numbers wherever possible.  Imprecision invites varying interpretations.
  20. Use of hidden assumptions.  I’ve heard writers say things like “Everyone knows that quartz is preferable to glass in this infrared application” or “Well, the sponsor obviously knows why we are changing our technical approach because he directed the change.  So we don’t need to say that in the report.” Wrong!  Assume nothing! In the latter example, the sponsor is only one of potentially several dozen (or hundred) eventual readers of a report, most of whom will never know why your firm abandoned a perfectly reasonable technical approach in favor of a very risky one, unless you tell them!  Omit that single detail and you are likely to be labeled foolish in later meetings where neither you nor your sponsor is present to explain your actions.
  21. Excessive use of the passive voice which makes for difficult reading and complicates a document.  Here are a few common examples:
    • “The system will be capable of  . . .”  or “the system will have the ability to . . .”  (just say “the system will…”)
    • “. . . consider implementation of . . .”  (say “implement”)
    • “It was decided that . . .”  (say, instead, “Our team decided . . .”)
    • Other examples to be avoided include “…is favored by . . .” and “it was concluded that . . .”
  22. Use of “shall” in place of “will”.  You aren’t writing a specification so don’t use “shall” which is typically a legal term in business agreements and has a “binding” connotation. Write like you speak.  Use action verbs and an active, future tense.
  23. Lawyer-talk:  Don’t try to use lofty words when a common one will do, for example obtain (use get), accede (use agree), aforementioned (use already discussed), subsequent (use later), cognizant of (use know).
  24. Run-on sentences. A sentence should have a single, main point, not several.  Take a meat cleaver to long sentences.
  25. Lengthy paragraphs.  Most technical writers use fewer than ten lines per paragraph.  Robert Gunning even has a “Fog Index©” that quantifies how easy a document is to read, based on length of words, sentences and paragraphs (see reading list item #3).  Even when you have no page-count restriction, strive for conciseness.  While perhaps not as crisp and unambiguous as German, English is still a wonderful technical language when used concisely.  (This one sentence, written in formal Arabic, could require 3-4 lines of text!)
  26. Excessive use of “which” when “that” would be clearer.
  27. Use of expletives leading to wordy sentences
    • There are, is, were, was, will be . . . .
    • It is, can, was . . .
  28. Awkward page breaks.  Hold thoughts together in the text, forcing a page break to occur where it makes the most sense to the reader.  The worst infraction here is to allow a table/figure caption to become separated from the table or figure. Almost as bad is allowing the first sentence of a section to begin at the bottom of a page: push it to the next page to be with its friends!
  29. Commas inserted where they aren’t needed at all and absent where they are needed.  If you would not actually pause there when reading the text aloud, then you should think twice before putting a comma there.   If in doubt, leave it out.
  30. Lack of proofreading by anyone other than the writer.  Silly mistakes are not caught.
  31. Lack of white space: paragraphs crammed tightly against paragraphs/graphics, with very few blank lines.  Even page-constrained documents need some white space to improve readability!  The human mind appreciates occasional white breaks in the monotony of black text – – – it seems to provide time for ideas to sink in before new ideas show up in the text.
  32. Use of 10-point type size, to cram text into a page-count-constrained document.  Use 12-point or larger and cut the amount of text to make things fit.  Many senior people cannot comfortably read 10-point type and may get annoyed if you force them to use their bifocals.  And an annoyed reader may not even know why he dislikes your report (and hence, your firm), just that he does.
  33. Inconsistent use of abbreviations, terms, capitalization, etc. within the same document.
  34. Overuse of underlines versus italics.  Don’t be boring.  Mix it up but be consistent within sentences.
  35. Failure to add page numbers.
  36. Failure to insert a blank line between paragraphs.
  37. Inconsistent use of indentures.
  38. In a CONOPS, failure to number the sections, making for difficult discussions about paragraphs/sections of interest.
  39. Inconsistent depth in the outline, with some sections a shallow 2-alpha and others at an almost microscopic 5-alpha.  The temptation is to include lots of data for areas where you have it, leaving other areas barren.  Don’t do it. Balance the outline and the body of the document, putting details in an appendix.
  40. Use of “e.g.” (for example) or “i.e.” (in other words).  Since many readers don’t know these definitions, and high schools don’t seem to be teaching much Latin these days, let’s stop using these terms.
  41. Pairing people with “that” or pairing objects with “who”.  Do not write about anyone “that” did something or said something.  Use “who” when referring to people.  Use “that” when referring to anything else (objects, organizations, etc.)
  42. Use of “reiterate” when “repeat’ would do fine.
  43. Excessive use of questions as the opening sentence in a paragraph.  Occasional use of this technique is fine but be aware that it forces the reader to move out of the passive-reception mental mode and actually think, which annoys some people.
  44. Excessive employment of “utilize” when “use” would work fine.
  45. Don’t use “in order to” when “to” works just fine. For example, instead of: “In order to complete the signal processing chain the filter must be tuned to…” use this more succinct and directed version: “To complete the signal processing chain the filter must be tuned to…”
  46. Lifting Power Point ™ graphics and plopping them into Word ™ documents without regard to complexity, applicability or suitability.  In these hurried times this is common but still criminal.  Build graphics from scratch with a pencil and paper, outlining them first to answer the two questions “what do I want this graphic to accomplish” (inform, persuade, explain, motivate, etc.) and “what would be the most effective, efficient possible graphic for that purpose?”.  Then search existing graphics for candidates and give STRONG consideration to using pieces of them to custom craft a crisp hybrid.
  47. Confusion of compose and comprise.  Roget’s Thesaurus© even has this wrong.  Compose is a verb in the music business and in specialized writing such as poetry.  Elsewhere the phrase “composed of” describes a single thing and is often used in place of “made up of”.  A single, complex thing can be composed of many smaller things. But Comprise describes an assembly of multiple things and means “make up” or “add up to”: multiple things can comprise a larger thing.  But published definitions for these two terms overlap so we suggest only infrequent and careful use of them, especially of comprise, to avoid confusion.  Instead of saying “The items inside this bag comprise all my personal effects” (which is correct usage) instead just say “This bag contains all my personal effects” and hand it to the jailer.  He probably won’t believe you and you’ll be strip-searched anyway.

Crisp, clear technical writing is a learned skill and increasingly in demand.  Crafting a crisp, well-worded section in a blog post, book, proposal or report is very satisfying.  And like any other difficult-to-master skill, becoming a good writer takes practice and effort.

Lastly, remember to submit your writings early to peers and others for review because none of us is as smart as all of us.

Suggested Reading List:

  1. The Elements of Style by Strunk and White, 4th Edition (a classic reference book, over 10 million copies sold, available at any major book store)
  2. Systems Engineering Handbook, International Conference on Systems Engineering (INCOSE), California, 2006
  3. Technical Writing, Process and Product by Steven and Sharon Gerson (Prentice Hall, 1992)

Copyright: Solid Thinking Corporation

Related Articles

Previous post:

Next post: