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.
>My concerns center around unnecessary clutter and filters to
>communications--users being required to wade through administrivial
>metablather before they get to the information they _need_ to do their
>task (even if the task is, Learn about this topic, as opposed to, Set
this
>widget to enable efficient frambling). So I'm thinking that change bars
>unnecessarily draw cognitive attention (redundant? not sure) to the bar
>itself instead of to the message at hand. That is, perhaps the user's
then
>drawn to a metamessage: "This line of information is different from
what
>it was at an earlier point." Instead, perhaps the user needs to know
the
>information itself.
Under some documentation conditions, this may indeed be true.
But sometimes the user really needs to know what information has
changed, and needs an easy way to figure out where those changes are
located. This may more often be the case in hardware procedures than in
software procedures, but at least that's where my mind first goes to
examples.
(BTW, that would fit in neatly with Joe's observation that the use of
change bars and change pages once was common, but now seems to be
disappearing. Once upon a time, all tech manuals were hardware manuals,
'cuz there was no software to document. The rise of software
documentation seems to be inversely proportional to the use of change
bars in docs.)
It really comes down to what the customer expectations are regarding the
marking of changes, and how they might come into play.
Let's assume you've got a procedure for assembling a complex object. In
the time since the last manual revision, there have been a few changes.
One, the writers discovered that the manual called out the wrong torque
value on the bolts. Two, the engineers came up with a newly approved
tool that makes the assembly job easier. Three, there is an actual
design change for newer models, so your procedure now must cover two
slightly different hardware configurations.
The new revision of the manual goes to a shop where the users have been
assembling this item for quite a while, and (now I know this next part
is really far fetched and it -rarely- happens in real life) by now the
users consider themselves familiar enough that they don't always read
the procedure step-by-step when they assemble the item. As a result,
subtle changes might get passed them, unless they become aware of those
changes.
Without change markings of any type, the users would have to sit down
and do a side-by-side comparison of the two tasks to learn what the
differences are. Okay, so the new configuration changes wouldn't affect
them...and maybe they don't have that new tool...but those different
torque values might just prevent some damage to the equipment. It could
even be a safety issue. So, the users really need to be aware of that
change.
Maybe I'm a pessimist, but my general assumption is that when my users
get a revised manual, they do -not- sit down and do side-by-side
comparisons to see what changed from the last rev. So, the change bars
are a useful tool for calling attention to differences between the new
and old.
This may not be as big an issue in software documentation. If a GUI
changes, in some ways the user is -forced- to face the change (literally
and figuratively). A new required field may send the user back to the
docs to look up the information that should go into the field, because
the user can't get to the next screen until that data is correctly
entered.
But sometimes it's easier to overlook changes in hardware procedures, so
the practice of highlighting those changes tends to be a good one.
Oh yeah, there's one additional reason why you might want to include the
change bars. It may not make a difference from the theory of technical
communication, but it might make a difference in the reality of business
practice: If your customers are paying for regular updates to the
documentation, change bars help demonstrate to the customers that
they're actually getting something for their money.
NEED TO PUBLISH FRAMEMAKER CONTENT ONLINE? "Mustang" is a NEW single
sourcing tool for FrameMaker that lets you easily publish your content
online. No macro language required! http://www.ehelp.com/techwr-l3
Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See www.mercer.edu/mstco or write George Hayhoe at hayhoe_g -at- mercer -dot- edu -dot-
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -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.
