ITinfo: Writing for the End User

Site Directory
Membership
Train-the-Trainer
Trainer Certification
Certified Training Materials
ITinfo E-zine
Responsible Training
White Papers
Trainer Resources
What's New
Speaking Engagements
Onsite Training
ITrain Gear

Technical Instructions

Don't forget for whom you're writing!

ITinfo Sponsor

ERROR: Random File Unopenable

The random file, as specified in the $random_file perl variable was unopenable.

The file was not found on your file system. This means that it has either not been created or the path you have specified in $trrandom_file is incorrect.

Writing for the End User

by Dave Murphy
ISSN 1535-3613

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:

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.

Open Windows Explorer
In the left column of Windows Explorer...
Scroll down and double click "clients"
Scroll down a bit more and double click "Abbot Corporation"
In the right column (the larger side) of Windows Explorer...
Click once on the file named "abbot-crm.mdb"
While continuing to let the mouse pointer touch the abbot-crm.mdb file...
Right click (a menu will appear)
Left click the option Cut
In the left column of Windows Explorer...
Scroll down to the folder named "history"
Double click "history"
Point your mouse to a blank area within the right column of Windows Explorer
Right click (a menu will appear)
Left click the option Paste
Confirm that the file abbot-crm.mdb now appears on the list of files in the right window
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

What do you think? Leave your comments on the message center.

References

Message Center

Additional articles related to creating better training materials faster are posted to ITrain's website in the Training Technology section.

Previous issues are on our website at http://itrain.org/itinfo/.

International Association of Information Technology Trainers
PMB 616
6030-M Marshalee Dr
Elkridge, MD 21075-5987

410.567.5366
1.888.290.6200
fax: 801.650.0423
Membership Director: member@itrain.org

Return to ITrain Homepage

http://itrain.org/itinfo/2002/it020212.html
updated February 12, 2002