Whether it is writing documentation, an article, PR comments, or just answering a question on Stack Overflow, writing is an underrated part of being a programmer.
Google has a technical writing course on its developer website. This includes pre-class material which consists of reading and some practice questions.
I spent the weekend going through this material. Reading through this course material has brought awareness to some of the areas I struggle with when it comes to technical writing. I highly encourage all programmers to take some time to read through it as well.
The estimated time to complete it is about two hours. In case you don’t have the two hours to spare, I created this list of the top takeaways I learned. This list consists of things I often find myself doing when writing any technical documentation. Hope that these tips are helpful for you too!
I’ll start this list off with something easy that is sometimes overlooked. Use the same word or term consistently throughout the document.
One topic that I often write about is React. A term that may appear when writing about React is create-react-app. I am sometimes tempted to shorten create-react-app to CRA. If you want to use a shortened version of a term, you can specify it in the document.
For example, the following sentence would be fine:
create-react-app (CRA)… When using CRA…
English was never my strong subject in school, and I still struggle with some of the basics to this day. Instead of me trying to explain the difference between active voice and passive voice, check out the following video.
When writing technical documentation, use active voice most of the time. Readers will usually convert passive voice to active voice mentally. Save them a step and write in active voice. Writing in active voice is typically shorter, which is a good thing.
To be honest, I was not sure what was even considered a strong verb. Once again, let me restate that English was not my strongest subject in school. However, using strong verbs helps to engage a reader and keep their attention.
To make things easier for you, the following is a list of weak verbs that are often used in technical writing:
- forms of be: is, are, am, was, were, etc.
If you use these a lot in your documentation, consider replacing them with stronger verbs.
Focus each sentence on a single idea. One idea for one sentence is a simple rule. If a sentence contains multiple thoughts, it is hard for a reader to follow along.
To make your sentences short and focused, consider doing the following:
- Convert a long sentence into multiple short sentences.
- Convert a long sentence into a list.
- Remove unnecessary words.
The three main lists in technical writing are the following:
- bulleted lists
- numbered lists
- embedded lists
In technical writing, bulleted lists or numbered lists are preferred over embedded lists.
Embedded lists make sentences too long and hard to follow. Use a bulleted list for unordered items; use a numbered list for ordered items.
When using a numbered list, start each item with an imperative verb.
An imperative verb is a command word. Words like create, open, and add, are all imperative verbs and can be used to start a sentence in a numbered list.
Consider the following example:
1. Create a new React project.
2. Open the project in your code editor.
3. Add a new file to the project.
When using a list or table, introduce each with an introductory sentence. This sentence should tell the reader what the list or table is about. It is recommended to use the word ‘following’ when introducing a list or table.
The following sentence starters can be used to introduce a list or table:
The following list…
Take the following steps to…
The following table…
Just like how one sentence should be for one idea, one paragraph should be for one topic.
Each paragraph should answer the questions: what, why, and how. Write a good paragraph by answering the following questions:
- What are you trying to tell the reader?
- Why is it important for the reader to know this?
- How should the reader use this knowledge?
In technical writing, consider who your audience is, and what they may or may not know.
For example, doctors will know medical terms, but software engineers may not. Software engineers will know programming terms, but doctors may not.
Determine what your audience will need to know in order to understand your documentation. Explain what they should be able to do after reading your documentation.
This is not specifically focusing on technical writing, but something I found useful.
The following is a short set of rules to follow when using semicolons:
- A semicolon unites highly related thoughts.
- The thought before and after the semicolon must be a complete sentence.
- If you flipped the two thoughts, the sentence should still make sense.
The following is one example of how to use a semicolon from earlier in the article:
Use a bulleted list for unordered items; use a numbered list for ordered items.