iTranslated by AI
Learning from Google's Technical Writing Course: Key Takeaways and Common Mistakes
Overview
When writing technical documents, it is important to keep in mind how to write "easy-to-understand" content. As a guideline for this, I refer to Google's technical writing course[1], which I use whenever I write technical documentation. It is published for free on the web and teaches key points for writing clear technical documents.
In this article, I will explain the key points based on Google's technical writing course, along with common mistakes I have made when writing technical articles.
In this installment, I will introduce the following two points:
- Use active voice (clarify the subject)
- Clearly define the target audience
Target Audience
- People who are currently writing technical documents or want to start
- People who want to learn the essential points of technical writing
- People who want to know concrete examples of common mistakes and how to improve them
- People who want to read a summary of Google's technical writing course (in English) in Japanese
Note: If you only wish to read it in Japanese, there are articles that translate Google's technical writing course into Japanese (related links are provided at the end of this article).
What is Not Covered in This Article
- This article does not explain the entire content of Google's technical writing course, but focuses on the points that I consider particularly important.
Note: For comprehensive explanations, please refer to the original material or other explanatory articles (related links are provided at the end of this article).
Points to Watch Out for in Technical Writing: A Summary of My Personal Experience
I will explain these in the order of the challenges I felt while actually writing technical articles.
Clearly Define the Target Audience
This is based on the Audience section of Google's technical writing course.
Summary
When writing technical documents, it is important to clearly identify the audience. At a minimum, you should consider the following points:
- The target audience's role
- The target audience's prior knowledge
- The target audience's goals
By the way, I have a personal rule that I "always write down the target audience" when I write technical documents. To add to this, I try to think about the following question:
- What value does the technical document I am about to write provide to the target audience?
Next, let's delve a bit deeper based on mistakes I made in my past articles.
Example 1: Not considering the target audience
The first example is "OSS Design Pattern Explanation Series: Utilizing the Iterator Pattern and Bad Code Examples".
Quite simply, the target audience was not written down (this was the first article I wrote, and I hadn't thought about the target audience at all).
My revision for this would be to explicitly state the target audience as follows:
Target Audience
- People who have studied design patterns but want to know concrete usage examples
- People who want to know code examples and disadvantages when design patterns are not used
The target audience is now clear. By stating the target audience at the beginning, there are the following benefits:
- Readers can look at the target audience and see if the content of the document and their goals match (if they don't, they can stop reading there)
- I, as the author, can write content better suited to the reader by clarifying the target audience
Regarding the second benefit for the author, considering the target audience would allow me to revise the original article in the following ways:
- Premise of "having studied design patterns" => I can omit the explanation of "What is the Iterator pattern?" within the article
- Premise of "wanting to know concrete examples" => Include more code examples in the article
- Premise of "wanting to know the disadvantages" => Include a table of advantages/disadvantages of the design pattern in the article
Example 2: Target audience of this article
As a second example, I have clearly stated the target audience for this article as well. As mentioned before, the following is the target audience:
Target Audience
- People who are writing technical documents or want to start
- People who want to learn the essential points of technical writing
- People who want to learn along with examples of common mistakes
- People who want to read it in Japanese rather than the Google technical writing course (English)
Based on the target audience above, I wrote this article being careful about points such as the following:
- Introducing technical writing by focusing on the essential points
- Including plenty of concrete examples of failure
Also, in the case of technical articles, differentiation from other articles is important. By clarifying the target audience, you can also consider "differentiation from other articles" at the same time.
(Note) In this article, I also included a "What is not covered in this article" section (i.e., those who are not the target audience). I believe that if "target audience" alone is insufficient, writing about "people who are not the target audience" makes it easier to prevent mismatches with readers.
Use Active Voice (Clarify the Subject)
This is based on the Active voice vs. passive voice section of Google's technical writing course.
Summary
It is important to use the active voice (and avoid the passive voice) in technical documentation. The reason for using the active voice is that the subject is clear, making it easier for readers to understand. Conversely, omitting the subject or overusing the passive voice makes the text difficult to read and can lead to misunderstandings.
Furthermore, the reason why using the active voice is important is that the subject tends to be omitted in Japanese compared to English. To emphasize this further, I believe that in Japanese documentation, it is essential to use the active voice with a clear subject.
In Japanese, not just the subject, but various words tend to be omitted. I believe it is a good practice to explicitly state not only the subject but also the objects—the characters, items, and entities involved (who is doing what to whom, whose item it is, etc.).
Next, I will introduce mistakes from my past articles.
Example 1: Multiple characters and the passive voice
The first example is from my article, "Explaining the Relationship Between Shared Locks/Exclusive Locks, Two-Phase Locking, and Transaction Isolation Levels in RDB Using Sequences" (here, I was intentionally careful about the phrasing):
Let's consider the same situation as the example thought of in READ UNCOMMITTED:
- Initial balance of A's account is 500 yen
- A wants to deposit 100 yen
- B wants to transfer 100 yen
This is the part where I explained a bank account example to describe database locking. I believe the subjects (A and B) are clear, making the text less prone to misunderstanding.
On the other hand, what I was originally going to write was the following text:
Let's consider the same situation as the example thought of in READ UNCOMMITTED:
- The initial balance of the account is 500 yen
- 100 yen is deposited
- 100 yen is transferred
Readers who read this might think, for example, the following (the reader is mentally converting the bold parts while reading):
Let's consider the same situation as the example thought of in READ UNCOMMITTED:
- Someone's initial balance of the account is 500 yen
- The account owner deposits 100 yen
- Someone else transfers 100 yen
Reading while converting mentally is a burden for the reader, makes it hard to read, and in some cases can lead to misunderstandings. To prevent this, it is important to use the active voice with a clear subject as in the first version.
Example 2: Use the imperative mood for procedural explanations
The second example is from the following entry in "What to do if ECS (EC2 launch type) never starts #Beginner":
I avoided this phenomenon with this method.
- Reduce the CPU and memory in "ECS > Task Definitions > Infrastructure requirements > Task size"
- Reduce the CPU and memory in "ECS > Task Definitions > Container > Resource allocation limits - (conditional)"
This describes troubleshooting steps for ECS. Here, too, the subject is omitted.
In this case, the subject is (subtly) me, the author. However, I need to think a bit more about it.
The purpose of this article (i.e., its target audience) is for "the reader to perform troubleshooting." Therefore, these are troubleshooting steps, and it is more appropriate to write them with the reader as the subject.
Thus, it can be rewritten as follows:
To avoid this phenomenon, please follow the steps below:
- Please set the CPU and memory to smaller values in "ECS > Task Definitions > Infrastructure requirements > Task size."
- Please set the CPU and memory to smaller values in "ECS > Task Definitions > Container > Resource allocation limits - (conditional)."
By using the imperative mood, it becomes clear that the subject is the reader, making the text easier for the reader to understand.
(Note) Google's technical writing course explains that the subject of the imperative mood is you (the reader). The imperative mood is active voice, as follows:
Sentences that start with an imperative verb are typically in active voice, even though they don't explicitly mention an actor. Instead, sentences that start with an imperative verb imply an actor. The implied actor is you.
Summary
I introduced points for technical writing by focusing on the following two items:
- Use active voice (clarify the subject)
- Clearly define the target audience
These two points are what I consider particularly important. Above all, it is essential that technical documentation can be clearly understood by the reader. For that purpose, keeping in mind to "use the active voice to clarify the subject" and "write with the target audience in mind" will make your writing much more effective.
Google's technical writing course introduces various points including the two mentioned above. For those who want to know more details, please refer to Google's technical writing course.
Related Links
- Google "Technical Writing" - Educational materials for technical writing published for free by Google.
- A translation/summary of Google's foundational technical writing educational materials - A blog introducing Google's "Technical Writing".
- Google's foundational technical writing educational materials were very good, so I want to introduce them - A blog introducing Google's "Technical Writing".
Discussion