Technical Instructions

Don't forget for whom you're writing!

Writing for the End User

IT professionals frequently forget to use language appropriate for end users when giving directions. When writing technical instructions you and your techie colleagues may understand follow incomplete instructions and fill in the missing commands, but the users we support have different skills, and they may require a bit more hand holding.

Take for example the following instructions that I would feel comfortable giving to one of my peers:

1. Move the Abbot Corporation CRM data to the history folder.

Although my instruction seems simple enough to you, it's probably because you understand the acronym CRM, know where the history folder is, and know how to correctly move a file or set of files across a directory structure.

If I were to give this instruction to an end user I' try to be more specific and to not assume as much knowledge. For example:

It's a sad thing to report, but Abbot Corporation has gone out of business. We will no longer have to keep their Customer Relationship Management (CRM) data active on our network. The following instructions will guide you through the process of moving the Abbot CRM database to your history folder.

1. Open Windows Explorer

   In the left column of Windows Explorer...

2. Scroll down and double click "clients"
3. Scroll down a bit more and double click "Abbot Corporation"

   In the right column (the larger side) of Windows Explorer...

4. Click once on the file named "abbot-crm.mdb"

   While continuing to let the mouse pointer touch the abbot-crm.mdb file...

5. Right click (a menu will appear)
6. Left click the option Cut

   In the left column of Windows Explorer...

7. Scroll down to the folder named "history"
8. Double click "history"
9. Point your mouse to a blank area within the right column of Windows Explorer
10. Right click (a menu will appear)
11. Left click the option Paste
12. Confirm that the file abbot-crm.mdb now appears on the list of files in the right window
13. Close Windows Explorer, you've moved the file to the history folder and it no longer exists in the active folder for Abbot Corporation

The first think you probably notice is that it takes a lot more words to document the steps when writing for a less-technical user. That's the breaks. Also, the detailed instructions make fewer assumptions about the user's skills. I've only assumed the user knows how to accurately move a mouse, click, open Windows Explorer, and use a vertical scroll bar.

Also, just about every adult I've trained asks "Should I left or right click?" if I leave out the word "left" in commands #6 and #11. You and I know that click means "left click," but when we're talking to end users, we're not talking to ourselves (usually).

ITrain is actively encouraging IT professionals, especially IT trainers, to write more. Write instruction manuals, write about being a trainer. Your written words will have an positive effect on your organization long after you've move onto new challenges. Take writing one step at a time. A little bit each day starts to really add up over time. And remember, if you write 20 sentences a day, you'll have a newsletter done in a week and a book by the end of the year.

Call for Comments

References

Related Articles

Damar Group, Ltd. helps business use technology.

ITINFO is again accepting sponsors. Sponsor messages are included in ITINFO's email newsletter and are permanently posted to DGL's website and online reference areas.

ITINFO is an electronic publication of Damar Group, Ltd., publisher of Training Express computer learning guides. Comments and submissions to info@dgl.com.

Previous issues are on our website at http://dgl.com/itinfo/.

updated February 12, 2002
http://dgl.com/itinfo/2002/it020212.html

Return to DGL homepage
Copyright © 2002, Damar Group, Ltd., All Rights Reserved