0

5 Tips To Write Better Instructional Documentation

Posted by Nik on February 16, 2011

If you’ve been charged with writing a document that is supposed to instruct someone else how to do something, today’s way of doing it more or less throws the old methods out the window.

1. Big Bombastic Headers

You’ll notice the headers on PCMech, such as the one right above this sentence, are huge. This is because they’re easier to see, read and know where you are in the document.

2. Less Words

Wrong way:

The following documentation explains how to use and operate the Fanny Whacker 2000.

Right way:

Instructions on how to use the Fanny Whacker 2000

Always remember this phrase when writing documentation: GET TO THE POINT AS FAST AS POSSIBLE.

3. Skip useless references

If the reference has nothing to do with the core instruction of what you’re attempting to describe, such as:

For further information on Fanny Whacker 2000’s Turnip Twaddler, please see document FU, subsection ID10T.

…don’t do that.

4. Date it. Always.

The date of when the documentation was written should be in the footer area of every page. If it’s an electronic document, the date is shown twice. Once at beginning, once at end.

You can write this as "Last Revised (insert date here)".

5. Warnings should always be posted before the point of no return

If there is something in your documentation which could potentially damage/destroy/obliterate something if performed incorrectly, this information should be placed directly after said instruction, be in plain sight (meaning on the same page) and accented.

Example:

Step 5. Cleaning the Fanny Whacker 2000

The FW2000’s paddles should be cleaned gently using a non-abrasive soft cloth.

WARNING: Only use ammonia-free solvent to prevent the FW2000 from exploding and resulting in your untimely death.

On a final note, good documentation is not from being super-descriptive about every single possible thing imaginable. Read your documentation and ask yourself, does it instruct properly? If the answer is yes, the next question is, does it instruct quickly? If yes, the documentation is good.

Leave a Reply

Your email address will not be published. Required fields are marked *


Disclaimer: Some pages on this site may include an affiliate link. This does not effect our editorial in any way.