Technical Writing Tips for Beginners

Introduction

I recently took the free technical writing course offered by Google and to say the least, it was clear, simple to understand, and very informative. In this article, I outline some of my key takeaways from the course.

The course comes in two parts:

1. Technical Writing One - focuses on technical writing fundamentals.
2. Technical Writing Two - focuses on intermediate topics
3. This article does not cover everything taught in the course. It’s only a high-level summary of some of the key points the course provides. I intend to give you a rough overview of what to expect if you take it.

Technical Writing One

The first part of the course covers the fundamentals of technical writing. These range from the proper use of grammar to the correct identification of your audience.

Use terms consistently

If you reference something with a certain name, make sure you use the same name across your document. Using a different name might confuse your readers.

Write acronyms properly

Before you start using acronyms, first, write out the full term followed by the acronym in brackets as shown below.

• Azure Resource Manager (ARM) templates are JSON documents that define the configurations responsible for deploying and managing infrastructure. ARM templates are cloud-specific.

Use active voice

A sentence with an active voice follows the subject + verb + target format. The sentence below is in active voice.

• A compiler (subject) translates (verb) code (target).

This sentence uses the passive voice.

• Code (subject) is translated (verb) by the compiler (subject)

Some of the tips the course gives about identifying active voice is using the present tense and looking out for verbs that end in ‘ed’ as they usually indicate the passive voice.

Sentences

Write your document using short sentences. To do this, express only a single idea in a sentence and convert long sentences into lists.

Paragraphs

Good paragraphs should focus on a single topic. The paragraph should state what the topic is, why it is important and how the reader can use the information presented. Additionally, create paragraphs that are not too short or too long.

Lists

There are two types of lists:

• Ordered Lists Use ordered lists when the meaning of your list depends on the order of its items. For example, when writing a step-by-step instruction.
• Unordered Lists Use unordered lists when the order is not important.

When writing lists:

• Include a colon in the introductory sentence.
• Capitalize each list item.
• Use consistent punctuation.
• All list items should either end with a period or without.
• Start an ordered list with an imperative verb. Imperative verbs refer to commands. For instance, you can use ‘Set up...’ or ‘Download...’

Target Audience

Defining the audience of the article helps you write according to their needs. To identify your audience, consider the following:

• What are your reader’s goals? What do they want to get from reading your article?
• What prior knowledge about the topic do they have? How in-depth do you need to explain the concepts or terms mentioned in your article?
• What will your audience achieve after reading your article?

Having a clear audience leads to a clear article that provides the necessary information to your readers.

Technical Writing Two

Creating an Outline

An outline represents the main ideas that your document will cover. Use the outline to group topics, move them around, and organize them in a way that creates an easy-to-understand flow.

Introducing a Document

The introduction sets the tone of your whole document. A poor introduction can dissuade your reader from reading further. The introduction should answer these questions:

• What is the document about?
• What are the prerequisites?
• What does the document not cover?

Writing headings

When writing headings:

• Prefer task-based headings. Use verbs that describe what is happening.
• Avoid following heading 2 directly with a heading 3. Add a small introduction of the heading 2.

How to Present Illustrations

Pictures speak a thousand words. Here are some tips you can follow when using illustrations:

• Create the caption first. It should:
• Be brief
• Explain the takeaway. What does the reader get?
• Focus the reader’s attention.
• Break down complex illustrations into separate illustrations then offer expanded details.
• Add visual cues on screenshots. e.g use call outs to direct the reader’s eyes

Writing Sample Code

Most technical documents need sample code snippers. The code shows how the concepts explained in the document work. Good sample code should:

• Compile with no errors.
• Provide the expected results.
• Be without security vulnerabilities.
• Follow language conventions.
• Be concise.
• Have descriptive variables and function names.

Explain how to run the sample code and include:

• Libraries you need
• Environmental variables

When writing code comments

• Avoid obvious comments.
• Keep it short and clear.
• Explain why the code is doing what it is doing.

Conclusion

That’s it! My key takeaways from the Google technical writing course. I hope you learned something new.

Thank you for reading.

Important Links

Google Technical Writing Course

The difference between active and passive voice