Author: Kealan Parr, Zhou Jiahui The original link: www.freecodecamp.org/news/what-g…
Technical writing, done by technical writers, is the process of writing and sharing information in a professional setting. In this article, the author summarizes what he learned after attending Google’s technical writing course from a first-person perspective. The examples are vivid and the article is easy to understand. Whether you are a Chinese technical writer, or you are planning to write in English, this article will give you some inspiration.
I recently completed a Technical writing course at Google in almost four hours and enjoyed it. There are small exercises throughout the course so you can test your learning as you go along.
This article will briefly describe what I learned from the course, and I will summarize the best parts of it. I hope that after reading this article, you can get a general idea of the course.
This course covers some grammatical rules and linguistic aspects of English. But I’ll explain them all in the earlier part of this article, so we’re on the same page. You don’t have to be a great writer to complete this course, which requires only a little English writing ability.
Let’s study hard together.
The introduction
First, a few concepts that will be covered in this article:
- Nouns: Nouns are used to give names to things such as Madame Kay, the Eiffel Tower, the manager.
- Pronouns: Pronouns are used instead of nouns such as I, you, we, they, he or it.
- Adjectives: Adjectives are used to describe nouns such as the friendly Mrs. Kay, the rusty Eiffel Tower, the good manager.
- Verbs: Verbs are used to express actions or states, such as fighting, running, typing, eating.
- Adverbs: Adverbs are used to describe verbs such as: to fight fiercely, to run cowardice, to type energetically, to eat timidly.
Write clearly and clearly
Clarity means how clearly your ideas are presented. In technical writing, your first task is to write clearly.
The use of pronouns
Whenever you use a pronoun, you should make sure that the pronoun reference is clear. Using pronouns can easily confuse readers. For example:
C++ is an old programming language, and JavaScript is an old programming language. But I still like the language.
Clams? What do you like? C++ or JavaScript? The pronoun reference here is not clear, which harms the clarity of the passage.
Pronouns should be used like this:
C++ is an old programming language, and JavaScript is an old programming language. But I still like the C++ language.
In general, when proofreading, use a noun instead of a pronoun if it’s not clear what the pronoun refers to. Using this or that is particularly prone to this problem. You want to make sure that whenever you use these pronouns, the pronoun is clearly referred to.
The use of Idioms
An idiom is a common phrase used to describe something. But some idioms make no sense to non-native speakers. Since idioms are only popular in your region or language, you should try to avoid using them in your technical writing.
Walking around the porridge (ga rundt grøten), chewing the fat, We are inflating a cow by talking and inflating a cow. When you write your essay, just make your meaning clear and use simple metaphors instead of idioms.
Write simply and to the point
Brevity is how short and clear your writing is.
A good software engineer spends as much time polishing his or her work deleting code as writing it. The same is true in writing. In general, the shorter the code, the better, because:
- Make it easier for others to read
- Makes code easier to maintain
- The extra lines of code increase the likelihood of errors
All of these ideas apply to technical writing as well.
Communicating what you want to say succinctly doesn’t take a day. You have to document carefully. You may even have to proofread the document many times — but it’s worth it.
Shorter sentences also inspire readers to keep reading, while a huge paragraph can sometimes scare the reader. Some readers, when they see a 1,000-word paragraph, simply cross it off the page.
Delete the sentence pattern “there be”
This is for technical English writing, in English “there be” sentence sentence almost can be eliminated, to express your point more briefly. The sentence patterns of “there be” are generally very general, which annoys the reader. We can reorganize sentences. Here are some examples:
- There is a lot of overlap between software and hardware.
- There are no multiple threads in JavaScript.
The improvements are as follows:
- Software and hardware have a lot of overlap.
- JavaScript does not have multiple threads.
Use fewer adjectives and adverbs
Adjectives and adverbs are often used in descriptive and creative writing, such as novels and poems.
Examples of adjectives Google gives are changing grass into lush green grass, or replacing lifeless sounding hair with silky, flowing hair.
The problem is that adverbs and adjectives are generally so loosely defined that they can make your technical writing sound like marketing.
Running code in production mode makes it run incredibly fast.
In contrast:
Running this code in production mode results in a 225% performance improvement.
Hope you agree that the second sentence is more precise and quantitative.
Use the list
When you have a long sentence with many elements in it, you should break it down into a list. For example, if you want to list the advantages of a certain technology, you can say that XX technology is a good choice because it:
- lightweight
- fast
- Easy to use
This is a simple example, but you should get the point. Lists are much more readable than an overly long sentence, and they retain the reader without interrupting your flow.
Choose the right list
If you do find a good place to use lists, choosing the right list is critical. You can use ordered lists like this:
- This is my ordered list
- Isn’t it beautiful?
You can also use unordered lists, like this:
- This is my unordered list
- It’s different, but it’s still cool
So what kind of list should you use?
In ordered lists, order is important. Try to make the instructions clearer by starting each number with an imperative verb, such as a recipe:
- Turn on the oven.
- Bake a cake.
Unordered lists work for everything else.
Unified list
Once you’ve learned what kind of lists to use, the next step is to help you use lists to their maximum potential, just to keep them consistent. What does unification mean?
Each item on your list should:
- Be consistent in grammar and punctuation
- Logic should be unified (every item in the list should be a logical child of the list)
- Keep case uniform
Let’s take a bad example:
- c++
- JAVASCRIPT?
- Rust!
- chocolate chip cookies
All three of these rules have not been followed.” The item “chocolate chip cookies” does not logically belong on the list; The case of each subitem is not uniform; Punctuation is inconsistent (readers wonder why “JAVASCRIPT” starts with “? “Rust” ends with “!” At the end.
Use the active voice
A sentence usually consists of a subject, object and verb. Let’s try writing some sentences:
I wrote a story.
I am the subject, the story is the object, and the writing is the verb.
I really admire Jack’s work.
I am the subject, the work is the object, and appreciation is the verb.
- The subject is the person doing the thing.
- The object is something that is done.
- A verb is what the subject does to the object.
The examples above are all in the active voice, because the subject acts on the object. Now, let’s change these examples to the passive voice:
I wrote the story.
Jack’s work is appreciated by me.
Besides being more powerful and direct, active voice has the following advantages:
- Easy to understand. Whenever people read the passive voice, they try to change the passive voice into the active voice. So to make it easier for readers to skip this step and go straight to reading, we’ll write in the active voice.
- Readers are more familiar with the ** active voice. Active voice will be much more familiar to readers because most of the sentences we encounter are in the active voice.
- The passive voice sometimes makes the meaning unclear, the subject unclear, and forces the reader to expend energy trying to guess who did what.
- Active voice is usually shorter than passive voice.
General writing skills
Let’s take a look at how to get the most out of a well-written essay.
Sentence level,
Developers know to maintain the principle of single responsibility for their code. Remember, the same principle applies to writing sentences. Express one idea clearly and briefly in a sentence, and then write another. Don’t use a lot of and also this and that too, don’t make our last sentence fragmentary. If your last sentence is fragmentary, break down the words after “and” to make it your last sentence.
The paragraph level
A paragraph should have a clear opening statement that explains the main idea of the paragraph.
The opening line should include:
- What are you trying to say?
- Why is it important?
- How should readers use this knowledge?
Let’s take an example:
Garp () is a function that returns the DELTA between the average and median of a data set. Many people believe that the average is always the truth. However, averages are easily influenced by a few very large or very small data points. [How to do: Call GARp () to help determine whether several very large or very small data points make too much impact on the average. When garp() is small, the average is more meaningful.
Jargon and context
Jargon is a technical term used in a field. Investors might talk about w8-BEN forms or SPAC. If you don’t work in the field, you have no idea what they’re talking about. If possible, remove all jargon and acronyms and explain to the reader what is difficult to understand.
Try to make your writing easy to understand, but still keep it moderately complex (don’t oversimplify!). . If your text is obscure or too complex to understand, the reader will not learn from it.
Don’t assume that your audience will know anything about it either. If you want to talk about something, either explain it or give a link. Some call this the Curse of Knowledge (you know too much).
Assume that your reader knows less than you do, so that knowledgeable readers can skip over what they already know and novices won’t be confused.
Word choice level
English is the dominant language of technical writing, but it is not necessarily the first language of readers. Try to use common, simple English words. You duck don’t have to talk about the excitement you find in polysyllabic words, or show off your flowery words.
Meta information
Should write a brief introduction
When writing an essay, it’s best to begin with a brief explanation of what you are discussing. This will help people understand exactly what you want to discuss before they read more.
Take care of the reader
Try to make your documents palatable to your readers. When writing on dev.to, you can use one tone; When you’re writing for freeCodeCamp News, you can use a different tone.
Consider your audience when writing your document. For example, if you’re going to explain your company’s structure to a wider audience outside the company, you’ll need to explain it more clearly because they know less about your company than your colleagues do.
Sometimes your readers aren’t even technical people, and you need to make it easier for your readers to understand.
summary
Let’s briefly review the main points we just discussed:
- Keep the text consistent
- Avoid ambiguous pronouns
- Use active voice whenever possible
- Be brief and concise
- Focus on one point in a sentence
- Use the list
- Delete unnecessary words
- Don’t use complicated English or jargon
- Keep lists unified
- Start with a summary of what you’re covering
- Take care of the reader of your document
- Decide on your main points at the beginning
conclusion
After I finished the Google Technical Writing course, I learned a lot. I hope this article has clarified some of these concepts.
When I write, I try to apply the advice I learn. Hopefully this will help with your writing as well. I learned a number of useful writing principles in the course that can be applied to any document I write or any technical article.
You can click here to find the courses I mentioned in this article.
If you like this article and want to know more, I’ll share mine on Twitter.
Course links: developers.google.com/tech-writin…
Original Twitter: twitter.com/kealanparr
Welcome to “Byte front end ByteFE”
Resume mailing address: [email protected]