Guide for Technical Writing 📝

You should follow the following tips while writing a Technical Document:-

Use terms consistently

Use the same word or term evenly in your document. Once you have named a component, CMP do not change its name to COMP.

Avoid ambiguous pronouns

Using pronouns improperly can create confusion for the reader. In such a case, you should simply avoid the pronoun and just reuse the noun. Consider the following pronoun guidelines while writing:

• Never use a pronoun before you introduced a noun.
• Place the pronoun as close as possible to the referring noun.
• If you introduce a second noun between your noun and your pronoun, reuse your noun instead of using a pronoun.

Use acronyms properly

Acronyms are shorter but actually, they take a longer time to process in the reader’s head. Consider following guidelines for using acronyms:-

• The acronym should be significantly shorter than the full term.
• Don’t define acronyms that would only be used a few times.

Prefer active voice to passive voice

Use the active voice most of the time due to the following reasons:-

• Most readers mentally convert the passive voice to an active voice which results in more preprocessing time for readers.
• Some passive sentences omit an actor altogether, which forces the reader to guess the actor’s identity.
• Active voice is generally shorter than passive voice.

Pick specific verbs over vague ones

Don’t use a small set of verbs repeatedly. It takes a little more time, but picking the right verb will produce better results. You should select verbs that are precise, strong, and specific to engage and educate your reader. Avoid using inexact, weak, or generic verbs, such as the following:

• forms of be: is, are, am, was, were, etc.
• occur
• happen

Focus each sentence on a single idea

You should limit each sentence to one idea, thought, or concept. An idea should be executed by each sentence as a single statement does in a program.

Convert some long sentences to lists A list resides within many long technical sentences. Whenever you see an embedded list of items or tasks within a long sentence, consider converting it into a bulleted or numbered list.

Eliminate unneeded words

Many sentences contain words that are not needed and just consume space. For example:-
“This FLINT-doc provides a detailed description of Project FLINT.”
can be written as:-
“This FLINT-doc describes Project FLINT.”

Use a numbered list when ordering is important and a bulleted list when ordering is irrelevant

For example:-
Use a bulleted list when rearranging items does not change the list’s meaning:
“Bash provides the following string manipulation mechanisms:

• deleting a substring from the start of a string
• reading an entire file into one string variable”

Use numbered list when rearranging its items would change the list’s meaning: “Take the following steps to reconfigure the server:

• Stop the server.
• Edit the configuration file.
• Restart the server.”

Start numbered list items with imperative words

An imperative verb is a command, such as open or start. For example, notice how all of the items in the following numbered list begin with an imperative verb:

1. Download the TODO app from Google Play or iTunes.
2. Configure the TODOapp’s settings.
3. Start the TODO app.

Introduce lists and tables appropriately

You should introduce each list and table with a sentence that tells readers what the list or table represents.

Create great opening sentences that establish a paragraph’s central point

The opening sentence is the most important sentence within a paragraph. Busy readers focus on opening sentences and sometimes skip over subsequent sentences. Thus focus your writing energy on opening sentences. Good opening sentences establish the paragraph’s central point.

Focus each paragraph on a single topic

A paragraph should represent an independent unit of logic. You should restrict each paragraph to the current topic. Don’t describe what will happen in a future topic or what happened in a past topic.

Determine what your audience needs to learn

You should make a list of everything your target audience needs to learn to accomplish goals. In some cases, the list should hold tasks that the target audience needs to perform_._

Fit documentation to your audience

You must create explanations that satisfy your audience’s curiosity rather than your own and make your audience satisfied with your content.

Establish your document’s key points at the start of the document Always ensure that the start of your document answers your readers’ essential questions. Always write a summary for long engineering documents. The summary must be very short, expect to spend a lot of time writing it. A boring or confusing summary decreases the reader’s interest.

These were the points, you should keep in mind while writing Technical Documentation and you can use this as a Check List. This blog summarizes all the points introduced in this course.