Communication is key. The greatest distance between two people is misunderstanding.
Take Aways
Most of the information from the Google course was a refresher, but I took away a couple new concepts I plan to implement in my own technical writing.
The key take aways for me were:
- Use Strong Verbs, preferring active voice to passive
- Reduce “There is..”/”There are..”
- Focus each sentence on a single idea.
- Reduce subordinate clauses
- Answer what, why, and how
- The Curse of Knowledge
- Blank to first draft is the hardest step, first draft to final is pretty easy.
Know your audience
Good documentation equation:
good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills
- Define your audience.
- Determine what your audience needs to learn.
- Fit documentation to your audience
Unfortunately for anyone reading this, I really write this for myself in the future. The documentation is mostly for me to look back at and use as reference.
Curse of Knowledge
From the text:
Experts often suffer from the curse of knowledge, which means that their expert understanding of a topic ruins their explanations to newcomers. As experts, it is easy to forget that novices don’t know what you already know. Novices might not understand explanations that make passing reference to subtle interactions and deep systems that the expert doesn’t stop to explain.
From the novice's point of view, the curse of knowledge is a "File not found" linker error due to a module not yet compiled.
Biggest Hiccups
Mixing tenses is still one of my hardest challenges. I run into this issue because I will run into a problem, discuss what the problem was, and then talk about current configurations. The posts are a mix of the past and the present so the tense ends up being a mix of both.