The 4 C's of good technical communication:
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.
Everything left out of the material is something the audience has to discover and work out for themselves later.
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.
Clarity is dependent upon correctness, concision, and even comprehensiveness, but also several other factors as well:
- Group like with like.
- Sequence pre-requisites before post-requisities.
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.
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.
Anticipate your audiences misapprehensions, and acknowledge common misconceptions. (An author who just recently learned a topic for themselves often has advantages in this regard.)
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.
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.
There are two primary failings in today's programming education:
-
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.
-
Very few authors provide proper intermediate material, and this creates a large gap between beginner and advanced material.