6.5 Technical Writing

A consulting project is only as good as how the results and recommendations are communicated, no matter how clever the analysis. We do not need to turn in reports that read like War and Peace, say, but the writing should not hinder the conveyance of insights; technical writing may be an acceptable way to achieve this.

The main reference for this section is [63]; additional useful references include: [64], [65], [66], [67], [68], and [69]. The information provided is meant to serve as a set of guidelines. Bend them as needed, but be consistent.

6.5.1 Basics

Technical writing (TW) is communication written for and about business and industry, focusing on products and services (and policies?), and how to manufacture, market, manage, deliver, use and/or explain them. Good TW should be precise, clear, and accurate.

Examples of TW may include:
  • CVs and résumés

  • software manuals

  • company websites

  • instructions that come with a device

  • a job description

  • a falafel recipe

  • help files

  • code comments

  • safety protocols

  • official e-mails

  • use cases

  • case studies

  • briefing notes

  • research papers

  • reports

  • theses

  • blog articles

  • etc.

 
TW is not prose which recounts the fictional tales of characters, or poetry which expresses deeply felt emotions through similes and metaphors; it does not narrate an occurrence/event or express an opinion; it does not report on news items; it does not focus on poetic images or describes personal experiences.

In other words, TW is neither literature, journalism, essay writing, nor personal recollections.

Communication Continuum

Literature is read for pleasure, essays for enlightenment, and journalism for news. TW is read to accomplish a job. Consequently, technical writing should be more denotative (provide direct definitions) than connotative (invoke emotional suggestions).

This communication continuum is illustrated in Figure 6.4.

The communication continuum [@Gerson].

Figure 6.4: The communication continuum [63].

For instance, compare Whitman’s When I Heard the Learn’d Astronomer [70] (creative writing):

When I heard the learn’d astronomer,
When the proofs, the figures, were ranged in columns before me,
When I was shown the charts and diagrams, to add, divide, and measure them,
When I, sitting, heard the astronomer where he lectured with much applause in the lecture-room,
How soon unaccountable I became tired and sick,
Till rising and gliding out I wander’d off by myself,
In the mystical moist night-air, and from time to time,
Look’d up in perfect silence at the stars.

with the definition of astronomy [71] (technical writing):

Astronomy (from Greek: \(\alpha\sigma\tau\rho o \nu o \mu\iota\alpha\), literally: the science that studies the laws of the stars) is a natural science that studies celestial objects and phenomena. It uses mathematics, physics, and chemistry in order to explain their origin and evolution. Objects of interest include planets, moons, stars, nebulae, galaxies, and comets. Relevant phenomena include supernova explosions, gamma ray bursts, quasars, blazars, pulsars, and cosmic microwave background radiation. More generally, astronomy studies everything that originates beyond Earth’s atmosphere. Cosmology is a branch of astronomy that studies the universe as a whole.

Astronomy is one of the oldest natural sciences. The early civilizations in recorded history made methodical observations of the night sky. These include the Babylonians, Greeks, Indians, Egyptians, Chinese, Maya, and many ancient indigenous peoples of the Americas. In the past, astronomy included disciplines as diverse as astrometry, celestial navigation, observational astronomy, and the making of calendars. Nowadays, professional astronomy is often said to be the same as astrophysics.

Creative writing is “prettier” (and can be snarkier, apparently…), but technical writing conveys precise information.

In the consulting and data science world, communication skills are essential – the best idea in the world is worthless if it cannot be communicated properly.

6.5.2 Components

TW sinks or swim based on five components (see Figure 6.5):

  • development – preparing and presenting evidence

  • grammar – spelling rules, syntax, conventions

  • document organization

  • style

  • document design – highlighting techniques, graphs

The 5 components of TW; comparison with essay writing [@Gerson].

Figure 6.5: The 5 components of TW; comparison with essay writing [63].

Development

Preparing and presenting evidence should be required for all sorts of writing. TW should use examples, anecdotes, testimony, data, and research; it starts with overall objectives, then gets into details (items, steps, etc.), demonstrating a logical progression throughout.

Research often includes finding information from various sources, which should be cited when required.

For quantitative writing, the presentation of data and evidence is crucial: TW should use paragraphs, but also charts, graphs, and tables, as necessary [63], [64].

As an example, we COULD describe how to how to put together a LEGO kit using words, but millions of kids the world over know that there is a much better approach (see Figure 6.6).

Build-a-shark LEGO instructions, with objective (what the assembled kit  should look like), step (enumerated sequence of images), and required pieces (ordered sequence of images) [LEGO].

Figure 6.6: Build-a-shark LEGO instructions, with objective (what the assembled kit should look like), step (enumerated sequence of images), and required pieces (ordered sequence of images) [LEGO].

Grammar

Consulting reports and communications which do not adhere to the common spelling and syntactic rules of English115 (and its conventions) might not be taken seriously by some clients.

Consultants will find the following suggestions helpful:

  • always use correct grammar and spelling, no matter what language their writing in – mistakes undermine what there trying to say;

  • look it up or get help from someone who knows when in doubt;

  • data scientist should use the second person and talk directly to the client and/or reader;

  • avoid slang, dawg!;

  • not be, like, real informal;

  • explain acronyms: there are many possible meanings for most TLAs.

Compare with the following list of second person suggestions:

  • always use correct grammar and spelling, no matter the language in which you write – mistakes undermine what you’re trying to say;

  • when in doubt, look it up or get help from someone who knows;

  • use the second person; talk directly to your client and/or reader (although some writers (ahem!) think that a (semi-)consistent use of person and voice is more important);

  • avoid slang;

  • don’t be informal;

  • explain acronyms: there are many possible meanings for most Three Letter Acronyms (TLAs).

Other suggestions/guidelines include:

  • using spell-checkers wisely;

  • avoiding tenses shift in the middle of a sentence;

  • writing sentences with a subject and a predicate (see [72] for definitions and examples);

  • not running sentences together – this makes them hard to understand;

  • making the antecedents of pronouns clear (see [73] for definitions and examples);

  • using correct punctuation: periods (‘.’) end sentences and commas (‘,’) separate dependent clauses;

  • putting punctuation and footnotes inside quotation marks and parentheses (we’re not a fan of this one, so we chose to ignore it);

  • minizing the use of semicolons (they tend to complicate TW);116

  • not using apostrophes to form a plural (“Lend me your CD’s!” is bad; “Lend me your CDs!” or “Lend me your CD” is better).

Writing technical English is not easy, especially for those of us for whom English is not a mother tongue. Most Canadian clients will recognize (and make allowances for) this reality, as long as the writing and grammar are consistent, but it remains to the consultant’s long-term benefit to make an effort (or to employ an editor).

Document Organization

TW does not usually employ

  • topic sentences (sentence summarizing the paragraph);

  • transitions between and within paragraphs, and

  • thesis statements (abstracts or summaries).

In a memo or a letter, the thesis statement is usually replaced by a subject line. TW uses short paragraphs (units of text consisting of a small number of sentences expressing a single idea, with support).

Transitional words and phrases can be replaced by:

  • enumerated lists;

  • bullet lists, and/or

  • headings and subheadings.

TW should contain sections, each consisting of an introduction, a body, and a conclusion; the most useful, general information should go first, and it should be followed with the required details.

Style

In genereal, TW should use

  • short, denotative words;

  • short, simple sentences; and

  • short paragraphs with charts (as required).

From a stylistic perspective, the focus should be on the audience and on the purpose.117

It is important to remember that TW readers do not necessarily have an interest in the subject matter itself. Nobody reads instructions for pleasure, for instance – TW is simply a means to an end.

Consider the following scenario: late at night on a deserted country road in the Winter, a driver hits a pothole and realizes that one of his tires has been perforated. He has never changed a tire in his entire life. Would the instructions on the Subaru website help him to do so?

Equipment necessary to change the tire are a lift jack and a wrench. Use the jack to lift the vehicle and pick the tire up off the ground. Then use the wrench to loosen the lug nuts on the wheel. Once all the lug nuts are loose, remove them one by one and keep them in a safe place nearby. After the lug nuts are removed, the wheel and tire can be removed from the car. If a spare wheel is being put in its place, locate the spare wheel under the flooring of the trunk area, and take it out. Place the spare tire onto the lug bolts, and repeat the removal process in reverse order. Start by screwing on each lug nut, and then once all the lug nuts are screwed on, use the wrench to tighten the wheel to the disc plate. After all the lug nuts are fully tightened, disengage the jack to bring the car back to the ground. Do not exceed 50 miles per hour using a spare and changing the spare back to a standard tire as soon as possible. [Subaru.com]

Document Design

Document design refers to the physical layout of the correspondence.

In general, TW uses highlighting techniques, such as graphics, lists (numbers, bullets), headings, and sectioning. A small number of different fonts, colours, and accents (bold, italics, underline) can help, but remember that “less is more” – it is best not to overdo things on that front.

For sequential instructions, numbered lists are recommended. Longer documents could include a table of contents and an index, as well a lists of figures and tables; hyperlinks can be used for online documents. In all cases, clipart and low-resolution images should be avoided.

Let us revisit the flat tire example from above. Was the information provided precise? Did it get the message across? Was it understandable? What, if anything, is it missing?

The user manual’s tire changing instructions are shown in Figure 6.7. Which approach works best?

Changing a flat tire, Subaru Outback 2016 user manual.Changing a flat tire, Subaru Outback 2016 user manual.Changing a flat tire, Subaru Outback 2016 user manual.Changing a flat tire, Subaru Outback 2016 user manual.

Figure 6.7: Changing a flat tire, Subaru Outback 2016 user manual.

6.5.3 Traits

Sound TW exhibits five traits:

  • clarity (organization);

  • conciseness (fluency/choice);

  • accessible document design (ideas and content);

  • audience recognition (voice), and

  • accuracy (writing conventions).

Let us discuss these traits one by one.

Clarity

The memo below is an example of unclear writing.

From: Manager Untel
To: New Employee Smith
Subject: Meeting

Please plan to prepare a presentation on sales. Make sure the information is very detailed. Thanks.

What don’t we know in this memo? What should have been included for clarity?

The journalist’s questions (6 Ws) can help clarify communications:

  • When’s the meeting?

  • Where’s the meeting?

  • Who’s the meeting for?

  • Why is this meeting being held?

  • What does the manager want to be conveyed about sales?

  • How much information is “very detailed”?

  • How will the presentation be made?

The same memo can be made much clearer, as below.

From: Manager Untel
To: New Employee Smith
Subject: Sales Staff Meeting

Please make a presentation on improved sales techniques for our sales staff. The meeting is planned for March 28, 2017, in Room 23, from 7:00am - 6:00pm.

Our quarterly sales are down 27%. We need to help our staff accomplish the following:
1. Make new contacts.
2. Close deals more effectively.
3. Earn a 25% profit margin on all sales.

Use the new multimedia presentation system to give your talk. With your help, I know our company can get back on track.

Thanks

Clarity is the most important criteria for effective TW. Without it, the reader will either need to contact the writer for further clarification, or just ignore the information: the writer’s and reader’s time is wasted, and the message is lost.

As another example, consider a furnace maintenance safety manual. If the writing is not clear and the reader fails to understand the content, we might encounter the following consequences:

  • BAD – the furnace is damaged. The company replaces the furnace, costs accrue, and public relations have been frayed;

  • ALSO PRETTY BAD – the company is sued and loses money, the writer gets fired;

  • WORSE – someone gets hurt, leading to pain, anxiety, bills (and bad public relations).

In a more general context, the 6 Ws should address the following items.

  • Who is the audience? Are they beginners or experts?

  • What do we want the audience to know or do?

  • When will the work/event occur, in what order?

  • Where will the work/event occur?

  • How should the tasks be performed?

  • Why is this information important?

It is preferable to avoid imprecise words, such as

many, few, short, often, recently, thin, etc.

and to use precise words and terminology instead, as in

“Don’t block the user interface thread for more than 2 seconds.”

“Use four inches of 26-gauge black wire.”

Another good suggestion is to front-load sentences with important information, as in

“Unfortunately, your program has timed out.”

“Network connection unavailable. Call 5555 for technical support.”

Conciseness

Consider the question asked in the 1980’s referendum on Québec independence:

The Government of Québec has made public its proposal to negotiate a new agreement with the rest of Canada, based on the equality of nations; this agreement would enable Québec to acquire the exclusive power to make its laws, levy its taxes and establish relations abroad – in other words, sovereignty – and at the same time to maintain with Canada an economic association including a common currency; any change in political status resulting from these negotiations will only be implemented with popular approval through another referendum; on these terms, do you give the Government of Québec the mandate to negotiate the proposed agreement between Québec and Canada?

How easy is it to understand the question? To remember what was read? How many of you even finished reading it?

How does it compare to:

“Do you want Québec to be independent?”

Text is concise when it says much with few words. The idea is to keep everything short and to the point. Conciseness is important as documents must often fit in a specific physical space: a résumé being at most 2 pages, a car owner’s manual must fit in the glove compartment, etc.

English is more concise when it avoids the passive voice: compare “Approximately 2000 records per minute are processed by the system” (10) with “The system processes approximately 2000 records per minute” (8).

Accessible Document Design

Consider the following paragraph:

Regarding part number 315564-000, we received 541 units of wafer #3206-2. These were rejected. For the same part number, we received 643 units of wafer #3206-4. These were accepted. Three hundred and twenty-nine units of wafer #3206-5 from the same part number. These were accepted. Next, 344 of part number 315564-000’s wafer #3206-6 were accepted. However, the 143 units of wafer #3206-7 (same part number) were rejected. Finally, all 906 units of wafer #3206-8 were rejected. These also were from part number 315564-00.

At a density of 8.4 words per sentence, the writing is concise; it is also clear, due to specificity of detail. But it is not intelligible.

Highlighting techniques open the text and make it inviting, while allowing for understanding and insight.

Document design refers to the physical layout of the communication (see previous sections). The document will be more accessible to the audience (in the sense that uninterested readers may still be able to digest it) if “walls of text” are avoided, and if tables are used to present information clearly (see Figure 6.8 for an accesible “re-write” of the passage above).

Accessible description -- part number 315564-000 [@Gerson].

Figure 6.8: Accessible description – part number 315564-000 [63].

Audience Recognition

Essentially, there are three kinds of TW audiences:

High-Tech Peers

readers in the same profession and at roughly the same level as the writer (or higher). Example: email to counterpart in another company;

Low-Tech Peers

readers who may not have the same level of expertise as the writer but who need to understand the subject. Example: summary of a software design document written for a manager;

Lay Readers

everybody else. Example: list of possible side-effects of a medication, written for a patient.

TW is different for each audience type. For instance:

  • high-tech peers/clients can handle acronyms and abbreviations;

  • low-tech peers/clients might also require parenthetical definitions, and

  • no acronym should be used for lay readers.

We provide an accessible description of audience recognition in Figure 6.9.

Accessible description of audience recognition concepts [@Gerson].

Figure 6.9: Accessible description of audience recognition concepts [63].

Accuracy

Finally, technical writing must be accurate: the information it reports must be correct and representative, with no crucial information missing. Inaccuracies can create nuisances, but can also be downright dangerous.

The difference between inaccuracy and imprecision is illustrated by the following statements: “Use 4 feet of 3/8-inch rebar” when the requirement is for 1/2-inch rebar (inaccuracy) vs. “Use 4 feet of rebar” does not specify the diameter, so the builder might not be sure (imprecision).

Writers use various tricks to help with accuracy, such as:

  • finishing the writing, letting it sit, then re-reading to see what might have been left out or gotten wrong;

  • have someone else read it;

  • reading it aloud slowly;

  • reading it backwards, or upside-down,

  • etc.

6.5.4 Example

Here is an example of what high-level technical writing could look like. This is a readable executive summary of the analysis of the algae blooms dataset conducted in sections 8.7 and 12.6 (based on a case study by [74]). It is obviously directed at a technical audience, but it does take into account the Multiple I’s as it weaves its narrative.

References

[63]
S. M. Gerson, A Teacher’s Guide to Technical Writing.” Kansas Curriculum Center, Washburn University.
[64]
[65]
M. H. Larock, J. C. Tressler, and C. E. Lewis, Mastering Effective English, 4th ed. Copp Clark Professional, 1980.
[66]
G. D. Gopen and J. A. Swan, The Science of Scientific Writing,” American Scientist, vol. Volume 78, 1990.
[67]
J. M. Williams, Style: Ten Lessons in Clarity and Grace. Pearson, 2004.
[68]
D. Hacker and N. Sommers, The Bedford Handbook, 9th ed. Bedford, 2013.
[69]
[70]
W. Whitman, When I Heard the Learn’d Astronomer.” 1865.
[71]
Wikipedia, Astronomy.” 2021.
[72]
The uOttawa Writing Centre, The Parts of the Sentence.
[73]
[74]
L. Torgo, Data Mining with R, 2nd ed. CRC Press, 2016.