Google has a technical writing course that I recently completed and highly enjoyed. It takes roughly 4 hours, and has some exercises along the way so you can test yourself.
I'm going to briefly explain what I learned from completing the course, and I'll summarise the best bits so you can get a good overview of what's covered.
We'll go over some grammar rules and linguistics for the English language, but I'll explain everything upfront so we're all on the same page. The only thing you need to complete the course is a "little writing proficiency in English", but "you don't have to be a strong writer".
Let's dive in.
Let's define some terms we are going to use throughout this document:
- Nouns are used to name something such as Mrs Kay, Eiffel Tower or manager.
- Pronouns are used instead of a noun such as I, you, we, them, he, or it.
- Adjectives are used to describe nouns such as friendly Mrs Kay, the rusty Eiffel Tower or the good manager.
- Verbs are doing words such as fight, run, type and eat.
- Adverbs describe verbs such as strongly fight, cowardly run, aggressively type and timidly eat.
Clarity describes how clear your point is in your writing. Your number one priority in technical writing is clarity.
Whenever you use pronouns, make sure they are clear. It's easy to get confused. Something like:
Clarify pronouns usage like:
Generally, when proof reading, if it's unclear to what you're referring, use the noun instead of the pronoun. This or that are especially prone to this issue. Make sure whenever you use these words it's clear what is being discussed.
Idioms are common phrases used to describe something. But some idioms mean nothing to an international audience. Because idioms are so specific to your region/language, try to avoid them in your technical writing.
No one understands what walking around the porridge, chewing the fat, or inflating a cow means intuitively. Just say exactly what you mean, and try to keep your analogies simple and idiom free.
Succinctness is how brief and clearly expressed your writing is.
Good software engineers spend as much time deleting code as writing it when polishing their work. It's the same in writing. Shorter code generally:
- Makes it easier for others to read
- Makes code easier to maintain
- Extra lines of code add extra points of failure
All of these points also apply to your technical writing.
Sometimes polishing and saying what you want to say succinctly takes time, and you have to really craft the document. You might even end up proof reading multiple times – but it is worthwhile.
Shorter sentences also encourage readers to continue reading. How intimidating is one huge paragraph? It can sometimes intimidate readers, and some readers will just bounce straight off your page when they see huge 1,000 word paragraphs.
Remove "there is" and "there are"
As you go through your writing, "there is" and "there are" can almost always be removed to more briefly express your point.
Both terms are generally very generic and bore readers. Rework the sentence. Here are some examples:
- There is a lot of overlap between software and hardware.
I hope you agree how much better these now read:
- Software and hardware have a lot of overlap.
Minimise use of adjectives and adverbs
Adjectives and adverbs are used a lot in descriptive, creative writing like fiction and poetry.
Google's example is turning "grass" into "verdant, prodigal grass" or turning the lifeless-sounding "hair" into "silky, flowing hair"
The trouble is that adverbs and adjectives are generally too loosely defined, and they can also make your technical writing sound like marketing.
Running the code in production mode makes the code run screamingly fast.
As opposed to:
Running the code in production mode will result in a 225% performance gain.
I hope you agree the second is more precise and quantifiable.
Make use of lists
When you have a long sentence with lots of elements in it, you should split it up into a list. For example, if you're listing the benefits of a particular technology, you could say, X is a great choice because:
- It's lightweight
- It's fast
- It's easy to use
While this is a simple example, you get the idea. This is now far more readable than an overly long sentence and you won't lose readers or your flow.
Use the right list
If you do find a good place to use a list, it's important to use the right list. You could use either a numbered list, like this:
- Here's my numbered list
- Isn't it pretty?
Or you can use a bulleted list, like this:
- Here's my bulleted list
- Different, but still cool
So which one should you use?
Use a numbered list, where the order matters, like say a recipe. Try to start each number with a commanding verb to reinforce the step by step instructions of the list, too:
- Turn on the oven.
- Bake the cake.
Bulleted lists work well for everything else.
Keep your lists parallel
Now you're hopefully using the right lists! The next step to help you use lists to their maximum potential is to keep them parallel. What does that mean?
Your list items should all have the same:
- Grammar and punctuation
- Logical categorisation (the list items reasonably all belong together)
Let's provide a bad example:
- chocolate chip cookies
Use Active Voice
Sentences are generally made up of subject, object and verb. Let's do a few as a test:
I wrote a story.
I am the subject, story is the object, and wrote is the verb.
I really admire Jake's work
I am the subject, Jake is the object and admire is the verb.
- The subject is the one doing the thing.
- The object is the thing being done to.
- The verb is what is being done to the object by the subject.
All of the above examples use active voice because the subject does the verb to the object. So let's flip those above examples to passive voice:
The story was written by me
Jake's work has my admiration (or Jake's work is admired by me)
You should use active voice because, in addition to being more powerful and direct:
- It's much easier to understand. Whenever people read the passive voice they have to make the mental effort to transfer passive voice to active voice. So for ease of reading, skip that step and write in the active voice.
- Active voice is far more familiar to the reader, as we read active voice writing most of the time
- Passive voice sometimes forces the reader to guess who did what in the sentence and obscures the meaning
- Active voice is generally shorter than passive voice.
General Writing Tips
Let's look at how to maximise each component of a well crafted written piece.
Developers are familiar with keeping their code single responsibility. Keep the same formula in mind for sentences.
Express one idea clearly and briefly, before moving onto the next sentence. Don't have lots of and also this and that too and even further splitting on our final sentence. If you end up doing that, split each text after the and into its own sentence.
Paragraphs should have a clear opening sentence to explain the paragraph's central point.
You also should clearly answer:
- What are you trying to convey?
- Why is it important?
- How should the reader use this knowledge?
Let's have an example that does all the above:
garp()function returns the delta between a dataset's mean and median. Many people believe unquestioningly that a mean always holds the truth. However, a mean is easily influenced by a few very large or very small data points.
garp()to help determine whether a few very large or very small data points are influencing the mean too much. A relatively small
garp()value suggests that the mean is more meaningful than when the
garp()value is relatively high.
Jargon and context
Jargon is the specialised terminology that a particular field uses.
Investors might talk about a W8-BEN form or SPACs. But if you're outside that field, you have no clue what's being discussed.
Where possible, remove all jargon and acronyms and briefly explain what something is.
Try to make your writing as plain and simple as possible, still giving due credit to the complexity of what you're discussing (don't oversimplify!). If your writing is difficult or complex to understand, it won't help anyone.
Don't assume knowledge either. If you want to talk about something, either explain it, or try to link to a good resource on it. Some refer to this as the Curse of Knowledge.
Assume your reader knows less than you, so experienced readers can just skim the parts they already know, and newbies don't get lost.
English is the dominant language for technical writing, but English is not always the first language of the reader. Try to stick to commonly used, simple English words.
You don't have to discuss the exuberance you find from polysyllabic words, flaunting your magniloquence.
Write an Introduction
When you write something, briefly explain at the beginning what you're going to cover. This can help people understand exactly what you're discussing before reading more.
Tailor your Contents to your Audience
Try and fit your document to your audience. When you write on dev.to you may write one way, and when you write on freeCodeCamp News you might write another way.
Compose your document to best suit the audience. For example, if you're explaining your company's architecture to a wider audience, you will have to explain things more thoroughly as there's less shared knowledge there than with your colleagues.
Sometime you may not even be writing for technical people, and you'll need to explain things in a less-complex way to aid their understanding.
Let's do a brief overview of what we covered:
- Try to be consistent through your writing
- Avoid ambiguous pronouns
- Prefer active voice
- Be succinct.
- Focus each sentence on one idea
- Make use of lists
- Focus on deleting unnecessary words
- Don't use complex English or jargon
- Keep lists parallel
- Open paragraphs with an overview of what you're covering
- Scope your document to your audience.
- Establish your key points at the start of your writing.
I hope this article has explained some helpful concepts Google taught me when I completed their technical writing course.
I am going to try and pick and choose the relevant parts of their advice as and when it applies to the writing I do, and I hope it helps you too. I found quite a few helpful rules here for me to apply to documentation or any technical writing I produce.
The course I referred to throughout this article can be found here.
I share my writing on Twitter if you enjoyed this article and want to see more.