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.
Subject:Re: Documenting enabled/disabled items From:gyaker -at- csc -dot- com To:techwr-l -at- lists -dot- raycomm -dot- com Date:Wed, 15 Dec 1999 11:57:41 -0500
I suppose my solution isn't the best, but since I've been documenting software
where the GUI was not given much attention and shows many inconsistencies, I've
been faithfully documenting the software. If I pointed out problems at this
point in our design process, I would be told that my concerns are not important
at the moment and that the developers have no time to fix their visual mistakes.
Therefore, my documentation is consistent with the application, yet since the
application is inconsistent I am ultimately inconsistent. But that's how I have
to play around here. Maybe in a few months these problems will be ironed out.
What can you do?
Although if you document these inconsistencies, when the developers have a
chance to fix things, it will be easy for them to know the exact problems that
need to be addressed. Once they do their part, it should be easy for you to
modify your documentation.
Another thing I've noticed that abstracts this problem: Regardless of audience,
on an individual level, some people like as much information as possible. Some
like as little as possible. The example I'm thinking specifically of is driving
directions: When I tell someone how to get somewhere or when I receive
directions, I want as many landmarks as possible: hills, corner stores, bridges,
etc. OTOH some people like as little 'noise' as possible as in "take the first
left, the third right, the 2nd left and left at the fork," and NO more. I think
this concept has nothing to do with the audience as a whole, but each reader's
personal learning preferences.
christina_tolliver -at- hotmail -dot- com on 12/13/99 12:12:32 PM
Please respond to christina_tolliver -at- hotmail -dot- com
To: techwr-l -at- lists -dot- raycomm -dot- com
cc: (bcc: Gil Yaker/CIV/CSC)
Subject: Documenting enabled/disabled items
After procedure steps, do you document which fields are enabled and which
are disabled? What are the advantages and disadvantages of doing so, or not?
My question pertains particularly to software that is not consistent in
appearance or behavior. In my company's software, fields with a white
background are not always editable, and fields with a gray background are
not always read-only. The current user documentation indicates when fields
become disabled or enabled. Here's an example.
2 Click the Add button.
The non-editable fields are disabled.
The editable fields are enabled.
Whether or not you would _word_ things this way, do you think such a
statement helps users? (Our users are familiar with Windows but are not
computer whizzes.) Would this example be more helpful if the specific field
names were listed? Then, the example might read this way.
2 Click the Add button.
The Host, Switch, and Equipment boxes are disabled.
The Calling Feature box is enabled.
If this kind of information is helpful to users, it's worth the maintenance
effort for us writers to keep up with what fields are enabled when. But if
this is just a case of stating the obvious, maybe it's not worth our effort.
Sponsored by Weisner Associates Inc., Online Information Services
Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based Help.
More info at http://www.weisner.com/train/ or mailto:training -at- weisner -dot- com -dot-
Sponsored by ForeignExchange (http://www.fxtrans.com/tw.htm)
Rely on ForeignExchange for responsive and professional
software localization and technical translation services.
You are currently subscribed to techwr-l as: gyaker -at- CSC -dot- COM
To unsubscribe send a blank email to leave-techwr-l-9991N -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.