Skip to content

Instantly share code, notes, and snippets.

@BrianWill BrianWill/tech_writing.md
Last active Sep 21, 2019

Embed
What would you like to do?
Rules for technical communication

In a recent talk, Siobhan Gibson and Kerry Turner from Unity layed out three key qualities of good technical communication:

  • accurate
  • concise
  • clear

It's a good short list, but the inclusion of clear feels to me like begging the question: clarity is a product of multiple factors, including both accuracy and concision. To better define clarity, we should expand the list and define these factors:

accurate

Don't spread false information or mischaracterize. Even small details add up, and a single wrong detail can impede conceptual understanding because it doesn't fit into the larger picture (or distorts the larger picture).

Sloppy wording is often not just hard to understand but also wrong.

concise

Concision not only saves the audience time, it cuts out distracting verbiage and helps avoid burying key information in a sea of boiler plate.

Audiences very often revisit sources, and concision makes it easier to relocate particular bits of information.

Smaller pieces are easier to rearrange, and so in practice, the more concise, the more authors are likely to work out an ideal structure.

explicit and concrete

Avoid vague abstractions and metaphors. A metaphor only loosely fits a mental image, so it's easy for a metaphor to convey the wrong mental image.

Be sure to explain how something works rather than just explain how it might be used. I want an explanation, not a sales pitch. Just showing me use cases means I still have to puzzle out how the thing works for myself.

When in doubt, favor nouns over pronouns. You know what you meant when you said 'it', but your audience might not.

targeted

Define your audience: who are they and what do they already know? What language and ideas are they comfortable with?

Having defined your audience, state these expectations up front so the audience knows if the material is designed for them.

predictive

Anticipate your audiences misapprehensions, and acknowledge common misconceptions. (An author who just recently learned a topic for themselves often has advantages in this regard.)

clean and consistent

Format and structure consistently. Every picture hanging crooked on the wall is a distraction.

Make verbs agree. Make constructions parallel. When in doubt, don't omit relative pronouns. Strunk & White, etc..

Use terms consistently. Avoid jumping between synonyms.

Be very careful about adverb placement! For example, I caught this bugged sentence recently:

Completing a job transitively completes all of that job's dependencies.

The 'transitively' here is meant to apply to what comes after it, not to what comes before, but either reading is valid English. The ambiguity is avoided in this version:

Completing a job will complete all of that job's dependencies transitively.

paced

People can absorb unfamiliar stuff only so fast. Don't assume everything previously covered has been perfectly absorbed.

Use practical examples to synthesize what's already been covered and also to regulate the delivery rate of new information and concepts.

structured

  • Group like with like.
  • Sequence pre-requisites before post-requisities.

comprehensive

Everything left out of the material is something the audience has to discover and work out for themselves later.

what most sources are doing wrong

There are two primary failings in today's programming education:

  1. Making material both structured and comprehensive is particulary difficult. Ideally, the entirety of a topic can be learned from a neatly consumable sequence with no omissions, but while it's easy to structure material over a small scope, as the scope grows, the harder it is to integrate every piece into a coherent whole. Authors should be much more ambitious on this front.

  2. Very few authors provide proper intermediate material, and this creates a large gap between beginner and advanced material.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.