6 Keys from Google Technical Writing

Contents

1. Grasp of the Readers for Clear Direction
2. Precautions When Using Certain Words
3. Things to Consider When Writing A Sentence 
4. Using Appropriate Lists and Tables 
5. Writing Effective Paragraphs
6. Coherent Editing

As the importance of technical writing emerged, Google provided resources related to technical writing. This article is based on data provided by Google.

1. Grasp of the Readers for Clear Direction

For proper technical writing, it is important to understand the reader before writing. Based on the reader’s basic knowledge, the difficulty of terms and content must be adjusted and the composition of the content should be varied according to the purpose of reading the text. You should also use appropriate idioms and proverbs according to your nationality or culture when writing the content.

Answer the questions below to identify the reader and specify the direction of the text.

1. Who is the reader?
2. What is the reader’s goal? And why do they read this text?
3. What does the reader already know before reading the document?
4. What should the reader know or be able to do after reading the document?

2. Precautions When Using Certain Words

Defining new terms

Link or briefly describe the new or unfamiliar terms appearing in the content.

Use acronym

If you use an acronym (abbreviation) if the original word length is long, you have to choose one of the forms to use. If a word is repeated less often, it is easier for the reader to understand the original without an acronym.

Refer clearly

If you're referring to a word that popped up again, you have to use the proper pronouns and nouns. However, be aware that if the preceding nouns and pronouns are more than five words away, or if they appear too often, the sentence becomes unclear.

3. Things to Consider When Writing A Sentence

Use appropriate passive and active sentences

Good Sentences are easily understood as soon as they are read. In particular, each language has different characteristics, so if you need the translation, you should place the word order according to the grammar of the arrival language. Try to use the active form so that the reader can understand it at once.

Write a short and clear sentence

Write one key point that you want to convey in each paragraph in a single line and every single line of content that does not deviate from that key point. Short sentences should be written according to the basic format in which subjects, narratives, and objects are put once, and by not omitting the subject, sentences can be written more accurately and naturally.

Use modifiers to a minimum

Technical writing avoids the frequent use of modifiers such as adverbs and adjectives. Instead, it is explained in detail using accurate figures, diagrams, graphs, etc.

4. Using Appropriate Lists and Tables

Use appropriate list symbols

Use the appropriate format for each list's features. For a detailed list that is in an unrelated or large order between lists, you can use shape symbols such as circles, diamonds, or squares, rather than numbers. But if there is an order, numbers are used.

Parallel checking

If you use bullet points, make sure that each item's sentence format or superordinate and subordinate concepts are parallel. If the original sentence ends in a word, the translated sentence must end in the same word.

5. Using Appropriate Lists and Tables

Writing an introductory paragraph that arouses interests

Readers read the introductory paragraph and decide whether to continue reading it or not. Therefore, starting the first sentence with a question mark in addition to the sentence that represents the topic can attract the reader's attention.

To represent each paragraph with a single topic

One paragraph should only explain one topic, so take away sentences that are not related to the topic of the paragraph.

Adjust the length of a paragraph

The longer the paragraph, the less interesting the reader will be. Therefore, it is good to organize a paragraph into three to five sentences. In addition, if one paragraph is too short, the context of the sentence may be inconsistent, so try to group the broken sentences into one paragraph.

Figure out the Intentions

Each paragraph should indicate what it wants to convey to the reader, why the reader should know it, and how to use the knowledge gained through the writing. If the composition of each paragraph is disorganized, the overall content of the text will lose direction.

If you have trouble writing, ask yourself, "What am I trying to say?" Answering yourself is what the document should be written.

6. Coherent Editing

After writing the content, unify the overall style. A fixed style guide is required to unify the style of the document. If there is an existing guide, revise the style of the writing accordingly, and if there is no guide related, refer to the style guide of Google and Apple to set the guide.

• Google Developer Documentation Style Guide
• Apple Style Guide
  

If you are unsure of the expression or tone you use when you revise, ask your colleagues or experts for help. Above all, it is most important to convey useful information clearly and directly, so it is recommended to modify it if there is anything difficult to understand from a third party's point of view.