summary of what I found relevant in this course
Using one of this techniques:
- If the term already exists, link to a good explanation
- Otherwise, define the term. If there are many new terms, create a glossary.
Apply unambiguous terms consistently throughout the document, don't change the definition's references. e.g (wrong):
Protocol Buffers provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs. e.g (right): Protocol Buffers (or protobufs for short) provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.
Define the full term along with the acronym in parenthesis, both in bold
This document is for engineers who are new to the Telekinetic Tactile Network (TTN) or need to understand how to order TTN replacement parts through finger motions.
Keep in mind that the readers will mentally translate the acronym in ther mind before they get used to it, so in fact, it takes a little more effort in the beggining, therefore, only use acronyms when there are considerably shorter than the original term and it will be frequently used throughout the document.
Using pronouns instead of reusing a noun might create ambiguous scenarios as in the phrases:
e.g:
Aparna and Phil share responsibilities with Maysam and Karan and they are the next ones on call.
The pronoun they could refer to any of the following:
- Aparna and Phil
- Maysam and Karan
- Aparna, Phil, Maysam, and Karan
e.g:
You may import Carambola data via your configuration file or dynamically at run time. This may be a security risk
The pronoun this could refer to any of the following:
- importing via the configuration file
- importing dynamically at run time
- both
Make the reference clearer:
Aparna and Phil share responsibilities with Maysam and Karan which are next in line
You may import Carambola data via your configuration file or dynamically at run time. The second option may be a security risk.
Prefer to reuse the noun
e.g:
Be careful when using Frambus or Carambola with HoobyScooby or BoiseFram because a bug in their core may cause accidental mass unfriending.
==>
Be careful when using Frambus or Carambola with HoobyScooby or BoiseFram because a bug in HoobyScooby's core may cause accidental mass unfriending.
Sentences in a technical document should be in the active voice most of the time.
Active voice : An actor acts on a target
actor + verb + target
e.g: "The player kicked the ball"
Passive voice : a target receives an action from the actor
target + verb + actor
e.g: "The ball was kicked by the player"
We should identify sentences in passive voice and convert them into active voice
Code is interpreted by Python
==>
Python interprets the code
Benefits of the active voice:
- Most readers convert passive to active voice mentally
- Passive voice reports the action indirectly
- Some passive voice sentences omit the actor altogether
- Active voice sentences are generally shorter
Techinical documets writers should aim to the clearest version of the sentences.
Avoid imprecise, weak, or generic verbs such as:
- forms of be: is, are, were, was [...]
- occur
- happen
| weak verb | strong verb |
|---|---|
| The error occurs when clicking the submit button | Clicking the submit button triggers the error |
| This error message happens when... | The system generates the error message when... |
| We are careful to ensure... | We carefully ensure... |
Replacing there is/are with a meaningful subject create a clearer experience to the reader.
e.g:
There is no guarantee that the updates will be received in sequential order.
==>
Clients might not receive the updates in sequential order.
There is a variable called met_trick that stores the current accuracy.
==>
A variable named met_trick stores the current accuracy / The met_trick variable stores the current accuracy.
Adjectives and adverbs tend to be too loosely defined and subjective for technical readers.
e.g:
Setting this flag makes the application run screamingly fast.
==>
Setting this flag makes the application run 225-250% faster.
The idea:
- Shorter documentation reads faster than longer documentation
- Shorter documentation is typically easier to mantein than longer ones
- Extra lines of documentation introduce additional complexity and more points of failure
A sentence should contain a single idea, thought or concept. We should find ways to transform long sentences with multiple ideas into multiple sentences with a single idea.
e.g:
The late 1950s was a key era for programming languages because IBM introduced FORTRAN in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way.
==>
The late 1950s was a key era for programming languages. IBM introduced FORTRAN in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively.