Monday, October 4, 2010


Assumptions are tricky. You have to take into consideration the skill level of the reader performing a task so you don't waste their on things they should already know. You also need to take care not to assume they know acronyms and terminology that is common within the company or industry, but not outside the company.

If you are documenting professional design software, you should be able to assume the reader knows how to open a Windows or Mac program and what a cursor is. You cannot assume they will be able to infer how layers work in Photoshop or how the filters work, unless that training is a prerequisite to your document.

In the early 1990's there was a trend for companies to do away with professional technical writers in favor of engineers or business analysts writing the documentation. The problem with this was those people were too close to their products. Have you ever tried following the user guide for a stereo amplifier that is filled unfamiliar jargon and missing steps?

A procedure needs to describe and illustrate every step that needs to be performed to satisfy the purpose and scope of the task. If the reader is required to remove a part, the steps need to tell them where the part is, how to remove whatever is necessary to allow it to be removed, and how to remove it. If there are any acronyms or unusual terms, define them. You need to mention all mounting hardware that has to be removed and the quantity to prevent the reader from missing any and possibly damaging the part. In other words, you need to make it as difficult as possible to the reader to make a mistake. That doesn't mean you need to tell the reader which direction to turn the screws, but you do need to point out any special tools needed and hazards that may be encountered.

No comments:

Post a Comment