Technical writing has become a big deal in the tech ecosystem. Whether you're writing documentation or just writing about some new cool technology you discovered, the ability to pass your message across precisely and effectively is key.

In a bid to further improve my writing I started to take Googles technical writing course which is great by the way, and I decided to do a little summary of some of the things I think are important for communicating effectively with your writing.

In this article, we're going to look at how we can format our Writings to be clear so that we can pass the message efficaciously to our readers. Here are some of the things we would cover:

• Words
• Document scope
• Active voice VS Passive voice

NOTE: This article will not immediately make you a better writer. Writers get better after writing consistently overtime

Words

"We researched documentation extensively, and it turns out that the best sentences in the world consist primarily of words." ~ Technical writing one

Yes, Google has jokes too :-)

Let's look at how we can properly format words in our documents so that they are not confusing to our readers and to make sure they pass a clear message.

Define new terms

When writing, it is important to spot terms that may be unfamiliar to your audience and define them. There are two ways you can do this;

• If the term already exists link to an existing explanation.
• If your document is introducing this term, be sure to define it, and if your document introduces multiple terms, collect the definitions into a glossary.

Use terms consistently

"If you change the name of a variable midway through a method, your code won’t compile. Similarly, if you rename a term in the middle of a document, your ideas won’t compile (in your users’ heads)."

When writing, try to use terms consistently so that your users don't struggle to understand what you mean. It is very important to not change terms midway through a sentence or paragraph. For example :

Hashnode provides a platform that lets you blog on your domain. node is also easy to set up.

Notice the inconsistency in the above sentence? It confuses the readers a little bit.

Use acronyms properly

On initial use of an acronym, spell out the full term and then put the acronym in parenthesis like so; Michael Arinze Nelson (MAN)

Things to note when working with acronyms :

• If you're going to use an acronym multiple times in a document make sure to spell out the full term first, then you can go on to use the acronym. For example :

" If no cache entry exists, the Mixer calls the OttoGroup Server (OGS) to fetch Ottos for the request. The OGS is a repository that holds all servable Ottos. The OGS is organized in a logical tree structure, with a root node and two levels of leaf nodes. The OGS root forwards the request to the leaves and collects the responses."

Notice how OttoGroup Server(OGS) was first spelt out, before we went on to use its acronym in the sentence?

• If the acronym would only be used a few times in your document consider using the full term instead.
• "Do not cycle back-and-forth between the acronym and the expanded version in the same document"

Document scope

Technical writing one says :

"A good document begins by defining its scope and A better document additionally defines its non-scope, that is, the topics not covered that the target audience might expect your document to cover. "

When writing, be sure to state your document's scope upfront so that readers have a sense of what the entire document entails. For example, paragraph 3 of this article states what this article covers.

Active voice VS Passive voice

"The vast majority of sentences in technical writing should be in an active voice."

It is good practice to write technical documents in an active voice because it is clear, direct, and short.

How to distinguish Active voice from Passive voice

In an active voice sentence, an actor acts on a target. It follows the formula :

Active voice sentence = actor + verb + target

Here's an example;

The computer performs two tasks simultaneously.

• actor : computer
• verb : perform
• target : task

Passive voice sentences reverse the active voice formula.

Passive voice sentence = target + verb + actor

Here's the same sentence but in passive voice

Two tasks were performed simultaneously by a computer.

• target: task
• Passive verb: were performed
• Actor: computer

Conclusion

"Comedy writers seek the funniest results, horror writers strive for the scariest, and technical writers aim for the clearest. In technical writing, clarity takes precedence over all other rules."

In technical writing, it is very important to communicate clearly and effectively to your readers so that they don't struggle to grasp your content before trying to understand the concept you're passing across.

Attributions

• developers.google.com/tech-writing/overview..

If you liked this summary and want to take the full course, click the link above.

please follow me on twitter @D_kingnelson