What I Learned from Google's Technical Writing One and Two
Today, developers usually use AI to write documentation because of its convenience and speed. With just an outline and a few keywords, AI can produce a huge number of documents. However, their content is still hard to read, which pushes more review effort onto people.
To judge and control how AI writes technical documentation, developers need to know the rules of clear technical writing. Google provides four Technical Writing courses: Technical Writing One, Technical Writing Two, Writing Helpful Error Messages, and Tech Writing for Accessibility.
This blog shows what the rules change in a real paragraph. It focuses only on the rules from the pre-class material of Technical Writing One and Technical Writing Two.
The rules in action: before and after
Before: a paragraph written by AI
I asked an AI to write a short introduction to these courses. The result:
An Overview of the Courses
In today's fast-paced world, it's crucial for developers to delve into technical writing. There are two courses that are offered by Google which can help developers to seamlessly improve their docs. This is important because documentation that is not written properly can cause confusion, and readers may give up, and the team will spend more time answering questions that should have been covered by the documents in the first place. To get started, the pre-class material should be read, then the exercises can be completed, and the class can be joined if you want. It should be noted that this training is free.
After: the same paragraph with the rules applied
Learning technical writing with Google's courses
Google offers two courses that can help developers improve documentation. Unclear documentation can cause confusion. Readers may give up, and the team will spend more time answering questions that the documentation should answer.
To get started:
- Read the pre-class material.
- Complete the exercises.
- If you want, join the class.
These courses are free.
What changed
The following tables list the rules the rewrite applies and what each one changed.
- Technical Writing One covers the building blocks of clear writing: words, sentences, lists, paragraphs, and documents.
| Unit | Rules | What changed |
|---|---|---|
| Short sentences | Eliminate unneeded words. Focus each sentence on a single idea. | The "fast-paced world" sentence, "seamlessly", and "It should be noted that" are gone. The long sentence with 3 ideas joined by "and" splits in two. |
| Clear sentences | Reduce there is and there are. | "There are two courses that are offered by Google" becomes "Google offers two courses". |
| Active voice | Prefer active voice to passive voice. | Google is the subject, and "should have been covered by" becomes "should answer". |
| Words | Avoid ambiguous pronouns. Use terms consistently. | "This is important" becomes "Unclear documentation". "Docs", "documents", and "documentation" become "documentation"; "this training" becomes "these courses". |
| Lists and tables | Use a numbered list when ordering is important and a bulleted list when ordering is irrelevant. Start numbered list items with imperative words. | The steps to get started move into a numbered list, and each step starts with a verb: "Read", "Complete", "Join". |
- Technical Writing Two covers the work around writing: self-editing, organizing large documents, illustrations, sample code, and large language models (LLMs).
| Unit | Rules | What changed |
|---|---|---|
| Organizing large docs | Choose headings that describe the task your reader is working on. | The heading names what the reader does, not a topic like "An Overview of the Courses". |
| Self-editing | Place conditions before instructions. | "Join the class if you want" becomes "If you want, join the class". |
Sentence rules are not enough
Every sentence in the rewrite follows the rules, but the paragraph is still hard to read. The rules in the tables work on single sentences. They clean each sentence but don't connect the sentences to each other.
The Paragraphs and Audience units of Technical Writing One cover this problem:
| Unit | Rules |
|---|---|
| Paragraphs | Establish a paragraph's central point in the first sentence. Focus each paragraph on a single topic. Answer what, why, and how. |
| Audience | Determine what your audience needs to learn. |
With these rules applied, the paragraph becomes:
Learning technical writing with Google's courses
Unclear documentation confuses readers, so they ask questions that the documentation should answer. Google offers two courses that teach developers to write clearer documentation.
To get started:
- Read the pre-class material.
- Complete the exercises.
- If you want, join the class.
These courses are free.
The first sentence shows the problem, the second shows the solution, and the list explains how to start.
Start writing better documentation today
Technical Writing One and Two take only a few hours of self-study, and they pay off every time someone reads what you write. If you are a developer who writes documentation, I highly recommend them.
You can start here: Google Technical Writing Courses