Chapter 1 of 9 · 4 practices · 3 min · 4-question quiz
Know your audience and purpose
Every good technical document starts with two decisions: who is reading, and what they need to do or know afterwards.
Start: Decide who the reader is before you write a word4 practices in this chapter
- 1Decide who the reader is before you write a wordGoogle's Technical Writing One course puts the core idea as a formula: You cannot fill a gap you have not measured. Before writing, answer: Role: engineers on your team, engineers on another team…
- 2Fight the curse of knowledge: explain what feels obvious to youThe course names the main trap for expert writers: the curse of knowledge. Experts forget what newcomers do not know, so their explanations skip steps, terms and context that a newcomer needs.
- 3State the scope, the non-scope and the key point at the startGoogle's course says a good document begins by defining its scope, and a better one also defines its non-scope: topics the reader might expect but that the document will not cover. It also suggests a…
- 4Pick one type of documentation per page, using DiátaxisThe Diátaxis framework identifies four distinct needs and four forms of documentation, and argues that documentation should be organised around them: Most confusing docs mix these: a tutorial…
Check yourself on this chapter
4 questions, right here once you are signed in. Your progress is saved as you read.