6 Basic Rules for Better Technical Writing to write better content

As a technical writer, there are various standards and guidelines that you need to take care of when you write or create new documentation.

By standards, I am referring here to the internationally accepted domain-related standards which you need to follow closely.

For instance, you need to comply with the standards of ATA100, or iSpec 2200, or S1000D when you write a maintenance manual in the Aerospace domain. 

Similarly, there is DITA which is used in most of the domains such as Mechanical, Telecommunication, Software, etc. 

With your growing experience in the technical writing field, you will become more familiar with the standards. However, there are certain thumb rules that you need to take care of to build the core part of your writing. These rules hold good for any domain.

You should understand that whatever you write should have good clarity for the end-user of your document to easily understand what you are trying to say with your writing. 

This article focuses on those basic thumb rules which will not only help to write with clarity but also create good reading satisfaction for the readers.

Table of Contents

• Words
• Paragraphs and sentences
• List items and tables
• Punctuations
• Capitalization
• Audience analysis
• Conclusion

6 Basic Rules for Better Technical Writing

I have compiled the basic but not exhaustive 6 rules. Keep reading.

1. Words

a) Avoid superfluous errors

Superfluous errors are caused by words that are extra or unnecessary. You should identify the word and delete them or replace them with a proper word.

Some examples of superfluous words are:

final conclusion, kindly requested, supposing if.

 

b) Consistency in using terms

Maintain consistency of using the specific terms in the complete set of documents. Do not use the same term with two different names. This will create confusion among the readers.

For example:

When you are referring to pasta in your writing, you should never mention macaroni instead of pasta in any place.

c) Use of abbreviation

When you are using abbreviation to refer to two or more large clusters of words, make sure that you expand the first one and add its corresponding short form in parenthesis and use a short form every time you use the word in the rest of the document.

d) Use of pronoun

A pronoun should be used sparingly. Improperly used pronouns will create errors. 

The pronouns- it, they, this, that, creates confusion among the readers. If not used properly, they can change the meaning of the sentence. Always try to use the noun instead.

e) Use the second person

Always use the second person to call the user such as the Administrator, the user, you. Do not use the third person or first person in technical documentation.

The "I" and "you" tone are perfect for content writing, just like this article as it helps to build more engagement with the readers. But this approach should not be followed in Technical Writing.

f) Use simple words

Recognize the various terms which can be unfamiliar to the audience. Instead, use the term which is accepted globally and easy to understand. 

You are not writing an essay to make the readers impressed by using complex vocabulary anyway.

2. Paragraphs and Sentences

a) Use shorter sentences

Write a great short description or a lead sentence. 

If the sentence is short, it is easier to understand and communicates the message clearly. It is also easy to maintain. 

When you are writing any description, focus on each paragraph to explain a single idea. 

When you are writing procedural steps, limit to only 1 instruction per step.

b) Use active voice

You should always use an active voice to describe ideas or concepts and write clear instructions. 

In some places though, passive voice cannot be avoided; use passive voice sparingly. The passive voice always hides the identity of the person who is doing the action and makes the sentence longer.

c) Answer the three questions in your paragraphs

While writing a paragraph you should try to answer the three w's as follows:

1. What is that you are trying to tell the reader?

2. Why is it important for the reader to know?

3. How the reader should use this knowledge?

d) Provide examples

Examples provide a real case scenario to the reader. It helps in the proper understanding of the message. If the reader can relate they will obviously understand better.

Like in this article I have used my never-ending love for pasta as an example. With that pasta love, I have tried to frame different examples for simple understanding.

e) Use conditional text before the main instruction

Any conditional text should not be used after the main instruction. The reason is simple, you let the user know about the effect before you state the cause.

For example:

Incorrect: Wear protective gloves before you touch the hot metal surface.

Correct: Before you touch the hot metal surface wear a protective glove.

Incorrect: Click Delete, to delete all the files on the repository.

Correct: To delete all the files on the repository, click Delete.

3. Listed Items and Tables

a) Use of the unordered list

As a writer, you have the freedom to choose either an ordered list or an unordered list. 

Use an unordered list when you want to list certain items which if rearranged will not change the list's meaning.

For example: 

The various ingredients required to make pasta are as follows:

1. Pasta

2. Vegetables

3. Spices

4. Sauce

b) Use of the ordered list

Use the ordered list when the sequence of items has a meaning and if changed the list meaning changes.

For example: 

The steps to cook pasta are as follows:

1. Boil pasta

2. Fry the vegetables

3. Add the boiled pasta

4. Add some sauce

 

c) Introduce each list and tables

You should always write an introductory line or a short description to explain the list or table which you are going to write. This makes the listed items and the tables more meaningful.

d) Use of tables

Tables are a great form of representing a complex and large number of data in a very clear and precise manner. 

As a writer you should always follow some standards to create the tables which are as follows:

1. Introduce the table.

2. Provide a table number and title if there are multiple tables.

3. Define the header row.

4. Adjust each cell alignment.

5. Adjust row and column width.

6. Use footnotes to explain any extra information or condition for a specific cell.

4. Punctuations

a) Period

Use period at the end of a declarative sentence and in abbreviations. 

You should also remember that a period should come inside a quotation mark placed at the end of the sentence. See the example in the “Quotation marks” section for more details.

Example.

Mr., etc., Inc., Vol., Ver.

b) Question mark

Use a question mark after the end of an interrogative sentence.

Example:

Do you know how to make pasta?

c) Quotation marks

Use quotation marks to cite the wordings.

Example:

I searched on google “How to make delicious pasta.”

d) Apostrophe

Use an apostrophe to contract the word and to indicate possession.

Example:

It’s my pasta on the table.

e) Comma

Use a comma to differentiate between the items in a series, before the start of conjunction, and when you are writing appositives.

Note the comma used before “and”. It is called the Serial comma or Oxford comma.

Example:

I had pasta, salad, and wine at dinner.

f) Hyphen

Use a hyphen to join words that serve as a single adjective before a noun. It is also used to join two words.

Example:

check-box, third-party.

g) Exclamation mark

Use the Exclamation mark to give a command or to denote a strong expression.

Example:

Stay Safe! Have fun!

h) Colon

Use a colon to introduce a list and before a final clause that explains a particular thing in the sentence.

Example:

1. The following ingredients are required to cook pasta:

2. I didn’t eat the Pasta: it was very oily.

I) Parentheses

Use parentheses to include any additional information in the sentence.

Example:

If you are reading my blog, you might be aware of my favorite food (pasta).

j) Semicolon

Use a semicolon to join two independent clauses that are not connected with coordinate conjunction.

Example:

Yes, I love pasta; it’s my favorite food.

5. Capitalization

1. You should not use capitalization on words randomly. Always use lowercase unless there is a specific reason for capitalizing such as starting word of a sentence or a noun etc.

2. Do not capitalize on the spelled-out form of an acronym unless the spelled-out form is a proper noun.

3. You should not capitalize words that are emphasized (in italics).

4. You should write the topic/section headings always in sentence case and never in title case.

Example:

Correct: Format the pen drive

Incorrect: Format the Pen Drive

6. Audience analysis

a) Declare your audience

It is a good practice to declare your audience at the starting of your document. 

This will help to set the mindset of the readers.

You can declare the audience anywhere at the starting of the document such as “Introduction” or in the overview of the product section.

You should answer the following three questions:

1. Who is your target audience?

2. What do your readers already know before they read the document?

3. What your readers are capable of doing after reading the document?

b) Know your document will be read by a layman

Always assume that the consumption of your creation (technical writings) will be done by a layman. A person who does not have any professional or subjective knowledge.

If you find that you have used terminologies that are complicated, then you should always try to explain them somewhere. Probably a glossary would be a great idea.  

You should never assume that the user of your product will have at least some knowledge and thus you are eligible to deep dive with complex terminologies. 

Conclusion

Consider this article as a basic checklist when you are working to create new documentation from scratch.  

No doubt you have to follow the standard guidelines such as DITA and MSTP or any other company prepared guidelines. But the rules discussed above in this article are expected to be known by you, yet no one is talking about them.

A good, experienced technical writer always keeps a check on the rules discussed above. What are your special rules which you follow?

Share your favorite rule and thoughts about this article in the comments section.

If you find this article helpful, please share it.

Thanks

Cheers 🍻