Guidelines for Writing Technical Instructions by George Herrera

Have you ever had to explain to somebody how to complete a technical task? Or how about walking somebody through setting up a simple solution to a problem? If you have, then you know how difficult it can be to show somebody the steps that it takes to accomplish a technical task. I am going to show you how can connect with your reader, no matter what level of experience, and walk them through a set of technical instructions.

The first and most important thing you must always keep in mind is that your reader can range from a level of no experience to an extensive level of background in the product and/or service that you’re trying to teach them about. With this in mind, Always expect your reader to know nothing about what you are walking them through. An expert can always scan through and skip parts of instructions, but a novice cannot extract information that is not there.

The next important thing to include in technical instructions if possible is PICTURES, PICTURES, and more PICTURES! Most people are visual learners. If one reads a text book for a solution to a problem, more often than not, the solution or how one gets to the solution is not clear until they are shown or see how to do it visually. This also helps to clear any of the reader’s confusion. If they are at a certain step that they are not sure they executed properly, a simple picture of where they should be can be of great help.

When you write your technical instructions, it is important to include descriptions or definitions where pertinent. Your reader is not going to want to search for explanations elsewhere. Remember; always expect your reader to know nothing about what you’re walking them through. There is a good chance that the jargon you use will not be easily translated or your certain product has originally labeled parts. This is the reason for definitions and descriptions.

Last but with no less importance, TEST! Read through your instructions step by step and make sure that you can understand each part. Make sure you test the instructions out on completely novice users. See if and where they have any problems with clarity of instruction or function. Take this time to make sure that your instructions are clear and simple. There is no reason for history or background information in instructions for a product. Get straight to the point!

Below is an example of my instructions for a company that develops web filtering and reporting for organizational users. The instructions describe how to setup a custom access policy for users. This custom access policy will block them from surfing all websites except for what is specified.




Custom Access Policy Setup for users


I have circled in red where the ‘Custom Access Policies’ selection is located below:


Step-by-step instructions below:



Step 1:
a. Right click ‘Custom Access Policies’.

b. Left-click ‘New’ then ‘Custom Access Policy’

Step 2:
Click on the ‘Individual Access Policy Type’ button in the ‘New Custom Access Policy Properties’ box.

Step 3:
Select the ‘Permission’ policy option and click ‘OK’.


Step 4:
Now select the ‘Allow’ tab on the ‘New Custom Access Policy Properties’ box and click ‘Add’.


Step 5:
a. Select the ‘URL’ option.

b. Click the ‘Details’ tab.

Step 6:
a. In the space provided, enter the desired website masks. For example, if you wanted to allow http://www.microsoft.com/ to be accessed, the entry in the URL(s) field would look like so: *.microsoft.com*;*//microsoft.com*
You can add separate masks at the same time by separating them with a semi-colon (;).

b. Click ‘OK’ and make sure the masks are entered correctly.

Step 7:
a. Now click the ‘Apply To’ tab.

b. Select the users or groups that the access policy will apply to and click ‘OK’. Your Custom Access Policy has now been set to the specified users or groups and will take effect momentarily.