Writing Tenets
January 08, 2022
Words
- define new terms that might be unfamiliar
- use terms consistently (you dont change variable names in the code)
- use acronyms properly ex: Telekinetic Tactile Network (TTN) to introduce the acronym to the reader
- problematic words: it, they, them, their, this, that. Make sure these cannot be misinterpreted for other things.
Active Voice
Technical documentation should usually be written in active voice.
Active Voice Sentence = actor + verb + target
example of active voice: The player kicks the soccer ball
passive verb = form of be + past participle verb
passive words
- be
- is, are
- was, were
past particle verb
A verb ending in ‘ed’
ex: interpreted, generated
double passive example:
the code is interpreted by Python and is compiled by C++
mix:
Pyton interprets the code, but code is compiled by C++
active:
Python interprets the code, but C++ compiles the code.