This article originally appeared on my blog kaykleinvogel.com. If you liked this article make sure to check out my others.👍
This article is for everybody that writes technical documents regularly. I will share with you the basic details from the Google Developer technical writing course part 1. This way you are able to write better documents that people are more likely to read.
Why am I doing this?
I will be writing more technical documentation soon. Since I'm not a native speaker, I wanted to improve my writing skills beforehand. Writing is probably one of the skills that are very important as you're constantly sharing knowledge with others. So writing clean and concise documents will always be a good skill to have.
The whole course is split into 2 parts and I just finished the first one. The whole procedure took me about 2 hours. Since I will probably forget quite a bit I'd wanted to create this article, to have a short reminder of the content that was covered.
What is covered here?
There were a lot of topics covered in the first part of the technical writing course; however, I only want to cover the most important ones here. The basic structure will cover how to:
- define and use new terms/acronyms
- write clear and concise sentences/paragraphs
- organize your document for your audience.
Terms and acronyms
People might not be familiar with the terms you are using on a daily base. That's why it is important to introduce terms to the reader. If the term is completely new you have to write your definition of it. Otherwise, you can use an existing definition (don't reinvent the wheel). You should also stay consistent with your naming. So don't use different words if you are talking about the same object.
If you want to use acronyms a similar rule is applied. Since nobody knows all acronyms you should introduce the ones you're using. For the introduction, you can use the long-form term and then follow it up with the acronym in parentheses. (To make the acronym stand out more it is a good thing to make it bold.)
"The Table of Content (TOC) is an important part of every paper. The TOC gives the reader an immediate impression on the topics covered within a paper."
Adding acronyms will add a new layer of complexity for the reader. Every time the reader reads an acronym he has to think about it; the reader will read out the long-form term in his mind. Therefore you should consider if you have to use acronyms. Two general cases to use acronyms are:
- When the acronym is much shorter than the long-form term.
- The acronym is seen multiple times in your document.
When you decided to use an acronym you should stay consistent with its use. Don't go back and forth between the long-form term and the acronym. To make life easier for your reader you can also have a collection of acronyms in your document. This allows the reader to have a single source of truth regarding all acronyms used in a document.
Writing clear and concise sentences / paragraphs
The goal of a technical writer should be to present information as clear as possible. To achieve this there is one general rule that should be used for every sentence and paragraph.
Every sentence and paragraph should be centered around a single idea. Everything contained in them should be related to this idea. If you find any sentences in a paragraph that don't support your main idea, move them to another paragraph where they are more fitting.
To clean up a sentence you should also avoid long and complicated sentences. They can be confusing for the reader and obscure your point. To make a sentence shorter and easier there are two methods:
- eliminate unnecessary words
- split up long sentences
Eliminating unnecessary words
There are multiple ways to express an idea. Some are longer; some are shorter. When you are writing a technical document you should choose the shorter one. When you remove filler words and "textual junk" you will save your readers time. Some common examples of lengthy expressions that can be replaced with a single word are:
- "at this point in time" vs. "now"
- "determine the location of" vs. "find"
- "is able to" vs. "can"
The lengthy versions might sound fancier than the concise ones. But there is another place for this. A technical document should stay as short as possible.
Splitting long sentences
A single long sentence can make your point harder to understand. It also reduces the comprehensibility of your text. When you're reducing the length of a sentence always keep in mind, that there is one idea per sentence. So this makes the first step – to determine each idea of the sentence you want to shorten. This gives you the first idea of where to split things up.
The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way.
After splitting this huge sentence the result could look like this:
The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively.
Another option to split up long sentences is to convert the sentence to a list. A clear signal that a list can be used are the conjunctions or and and. When you use a list there are two options you can choose from:
- An ordered list can be used to refactor items that need a specific order to be logical.
- An unordered list is used for items that make sense no matter the order.
Organizing your document
So now that we have looked into the specific details of writing a document; we now have to see how to organize your document as a whole. As every document is unique I don't want to go to much into the details here but rather establish some key points.
define the scope of your document
Nobody likes to read 20 pages of a document to realize, that it doesn't contain the details you need. For this reason, you should state the scope of your document at the beginning. Now people can immediately see if your document is useful for them or not.\
For additional details, you can also include a "no-scope" where you explain what is not included in your document. Also, write an executive summary (a TL;DR) when you write a long document. This spares people the time of reading all 105 pages of your document and allows them to get a quick idea about the document.
define your audience
It is important to know who you are writing for. Depending on your audience there are a few aspects of your document that can change:
- language used
- level of detail
- topics covered
For example, if you're writing for a class of recent computer science graduates you might not have to go into the details of different algorithms. They probably had a class about algorithms and are familiar with the functionality of them. If the same document, on the other hand, is for people that have been out of college for a while you might have to go more into the details here.
structure your documents
A step that is overlooked quite often is the structure of the document. A good approach for this is to start from a general perspective and then go more into the specifics. With this approach, a reader can first learn about the basic concepts that are needed for the advanced topics that will come later. Using this order the reader can also prepare for what will come later.\
Lets take a document about sorting algorithms for example. It is a good practice to start with simpler algorithms like bubble sort. After the reader has finished this chapter he is in a "flow" and more likely to understand more complex concepts like quicksort.
Summary
Many aspects of your document can be changed to improve readability. The main aspects you should remember are:
- define new terms and acronyms
- use short and concise sentences
- one idea per paragraph/sentence
- tell the reader what the document is about
- structure your document in a sensible way
Top comments (0)