⇐ ⇐ ⇑ Course overview ⇑ ⇒ Planning ⇒
There are a few fundamental things to understand before you start the course. They come back again and again as you study. Remember them when you write.
Good techical writing
In secondary school, your teachers probably taught you lots of grammar rules, and graded you on how well you followed them.
But now you’re in the real world, and the goal of writing is no longer to get good grades. Writing is a tool, the means to an end. And that end is getting information from your brain into your reader’s brain.
Good technical writing is writing that communicates.
Rule Zero
|
|
So if good technical writing is writing that communicates, can we just throw away all the rules?
Not so fast.
Writing rules exist for a reason. You’ll find that writing that communicates to your readers is more likely to follow the rules than than to break them. But there are times when the rules get in the way. (Some of them are covered in this course.)
If you have to choose between communicating with your audience and sticking to the rules, break the rules. They’re really just guidelines.
Cognitive load
Cognitive load is probably the most important concept in technical writing. It’s basically the work our readers have to do to learn from what we’ve written.
The mental effort required to learn new information
(John Sweller, 1988, image via Wikipeda)
As technical writers, there’s nothing we can do about the two bottom layers of the diagram. They’re determined by the subject we’re discussing and the nature of the human brain. We can only control the top level, extraneous cognitive load: the load imposed by how we present information.
Most technical writing rules are just well-tried ways of reducing extraneous cognitive load as much as possible, for as many people as possible. Because people are different, you can’t make things easy for everyone. There is no perfect solution, just a lot of judgment calls.
(You can, however, make it difficult for everyone. Don’t.)
Cognitive styles
Different people think differently.
Verbal thinkers "Please explain what you want me to do." |
Visual thinkers 
|
Cognitive styles are the reason you can’t reduce everyone’s extraneous cognitive load to zero. Some people absorb verbal information best and just want you to tell them what they need to know. Others learn through pictures and diagrams, and find words tiring.
IKEA instructions are the perfect litmus test: some people find them delightfully clear. Others can’t make head or tail of them.
Both kinds of people are first class citizens of your information. Where possible, find ways to cater to both of them. This course focuses on technical writing but you should also include visual elements in your documentation. Note that the images shouldn’t just be decoration. They have to strike to the heart of what you’re explaining.
Style guides
Writing style guides are tools to make your writing consistent with the people you work with. That way the documentation doesn’t have distracting changes in voice and style. Style guides explain how to write, how to format different types of text, and even how to spell and punctuate common technical terms (wifi? WiFi? Wi-Fi?).
This course follows to the Google Developer Documentation Style Guide. The guide itself has more details and examples.
Ask if your organization/project has a style guide. If it does, and that guide disagrees with anything in this course, follow the guide rather than the course. If your organization/project doesn’t have a style guide, it’s time to adopt one.
⇐ ⇐ ⇑ Course overview ⇑ ⇒ Planning ⇒