Technical Writers have to remember these as well

Technical Writing is Comprehensive

If you are explaining the functions of the buttons on a toolbar, you need to explain ALL of them.

If a gadget has two communication ports, you need to explain how each of them is used.

Any error in covering all items in a document means an eventual call to customer service. Do not pass on the responsibility of serving the end-user right to another department by skimping on the information.

Technical Writing is Logical and Sequential

Technical writing information cannot contradict itself. All information, all steps need to make sense with respect to one another.

If you need to open a lid in order to reach a button, you need to tell the reader to open the lid first and then to press the button.

Do not instruct the user to press the button and then open the lid.

Technical Writing is Action Oriented

You are writing a document to help users take action.

Therefore, use action verbs whenever possible, especially in the beginning of procedural steps.

BAD: “Cable A and Cable Z need to be connected now.”

BETTER: “Connect Cable A to Cable Z.”

BAD: “Memory leaks will drop the efficiency of data retrieval and thus watch out against such an eventuality.”

BETTER: “Report any memory leaks immediately.”

Technical Writing is Organized

Technical documents are organized in the ideal “tree view” fashion.

The material is organized in layers, from general to specific.

The document starts with the general aspects of a system and drills down to more specific details later on.

For example, you explain what the CardPro software accomplishes first (controls access to power plant sites), BEFORE you explain the way to configure a card with the user info.

The individual chapters and sections should have a logical parent-child-sibling relationship with one another.

For example, if you are explaining how to start an engine in Chapter 1, you should also explain how to shut it off within the same chapter since they are conceptually related procedures (“siblings”).

The information on how to delete a user from the database (“child”) should be placed within a more general chapter or section (“parent”) devoted to User Configuration, or Database Management, just to give an example.

I hope now you have a better idea about the kind of discipline and vigor we need to make our technical documents stand out and shine.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Sumanta Biswas

A binge reader, especially detective and mystery novels. An ardent follower of cricket, football, and tennis, a die-hard Subhman Gill fan.