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.
Nothing in Nancy's message gave a reason, from the perspective of the
user, WHY for the changes...just a list of suggested changes.
Maybe...just maybe, the help is working the way it is. OTOH, maybe
not.
Before changing, wouldn't it make sense to know what the best thing
would be TO change?
> Nancy Mignone feels dissatisfied with the existing online help
> and wants to improve on it.
Improve WHAT?
> > Have people expressed problems?
>
> The users may not have a clearcut way to deliver feedback to the
> docs people,
Ask them. Just a few of them. Maybe the Beta testers. I've been at
gigs where the client executive asked for volunteers...two or three
of his biggest clients, to be contacted directly to be asked a few
questions. You'll find that those clients take it as a compliment to
be asked for their feedback in the form of intelligent conversation.
> > Would added colors contribute to its understanding? Would
> pictures
> > allow greater depth and dimension to your explanations?
>
> John, these sound like rhetorical questions... <g> The overall
> feeling I get
> from your response is that you feel the visual stuff is strictly
> window dressing
> to be applied (optionally) once the content is solid. I'd argue
> that the visual
> stuff is *part* of the content. Sprinkling some checkmarks and
We've all received/been given documentation that was VERY attractive.
Good use of white space, chunking, great visual stuff. That is, until
you started reading it. It was out of date, poorly written, factually
inaccurate. Was it a good document? OTOH, we've seen read.me files
written in courier, no formatting. The content made you weep with
pleasure.
To which one do you want your name associated? All I'm saying is that
before you create a visually appealing deliverable, make sure it
isn't built on a weak foundation.
Take 10 clients. Ask them their opinion of a formatted document. You
will get opinions from "I like it" to "I hate it". Give those same 10
users documentation that is not accurate, maybe even misleading. All
ten, if they used the document, will say the documentation is wrong.
Visual is mostly subjective. Facts are always objctive.
> the help easier to use.
Doesn't "easier to use" rely more on the instructions being correct
and actually applied to the correct version of the application than
whether it was written in mundane Times Roman/Helvetica with little
whitespace or easy-to read Garramound with liberal whitespace?
> > Keep in mind that whatever you add, you are adding to the
> maintenance.
>
> If I worked in a place where the attitude was "don't improve on the
> docs because
> it'll add to the maintenance," I'd be pining for a new job. Been
How about "Don't make the design of the document more complex to
maintain unless you can prove that the increase maintenance is more
than offset by the increase in usability." I'm not against
change...except for the sake of change itself. To add 5 more
different styles to a 3-style document without a reason for the
styles is only adding styles...nothing more.
> to ascertain whether I would be allowed to do the job right. Call
> me an idealist.
Right is making the best document you can under the conditions that
you have. If I have twice as long, my document will be twive as
righter. OTOH, which is more important to a corporation? 12 weeks to
do a help file that is 90% accurate and an STC winner, or 9 weeks for
97% accuracy that is not as pretty, yet beat competition to market by
3 weeks?.
> I admire the impulse to improve on the help file,
> even--especially!--if nobody
> has specifically asked for improvements. Go Nancy!
Spend some time to find out the change that will make the most
difference in the shortest period of time. Maybe its rewriting the
content. I also admire the impulse to improve documentation. Now,
find out what would be the best to improve.
__________________________________________________
Do You Yahoo!?
Yahoo! GeoCities - quick and easy web site hosting, just $8.95/month. http://geocities.yahoo.com/ps/info1
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr
---
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.
