TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Julie Tholen wanted to know about writing manuals for GUI products:
How do you handle GUI? How much field definition do you do? Do you specify implication of choices? Do you provide an overview of a task and then follow the screen-path to its
completion? Do you like to use lots of screen captures or do you leave that to the training department?
I prefer task-oriented explanations with enough visuals to help the user relate to the screen, but not so many screen captures that it becomes overwhelming. I believe in giving the users credit for being intelligent enough to *look* at the screen while working with the manual. At some point you may need to have all of the fields identified and thoroughly explained, but that can be done in a section at the back of the book. The important thing is to help the users a) find their way around the product so they can explore and learn on their own (and the interface should help them do that), and b) figure out how to do the tasks they bought the program to accomplish.
The screen captures should be pictures of things that are tricky to do or to explain. They should eliminate any confusion, and "be worth 1000 words" by showing the user something in one graphic that would take many paragraphs to explain. Use screen captures where most of your users will see the same thing, not where the image might be different depending upon their OS, configuration of equipment, etc.
Be sure to TEST the manual against the product before release, and make sure your graphics are absolutely correct. If there are changes to the interface after you have grabbed your screen, go back and re-capture. I can't emphasize this enough. If the user looks at the screen and sees something different than what's in the manual, that destroys your credibility. If you have to go to press earlier than the testing phase, try to get commitment from the developers that the interface won't change (good luck!). Or, avoid using graphics of elements that might change.
And if you're very VERY lucky, you will be part of the design team so that you can help make the interface more intuitive for users *before* it's coded, and then your manual won't have to be so long. The interface itself should indicate to users what the implications of choices might be, i.e., whether they'll expect to see a dialog box, or whether an operation will initiate.
--Beth
Beth Agnew
Senior Technical Writer, InSystems Technologies Inc.
bagnew -at- insystems -dot- com Tel: (905) 513-1400 ext. 280
Fax: (905) 513-1419
Visit us at: http://www.insystems.com
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
