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:Design Tips for Eric (way long) From:"Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM> Date:Thu, 8 Feb 1996 16:57:59 -0800
Eric Ray wrote:
>For example, I'm writing this note while breaking from a
>documentation/training project. My colleague and I are
>collecting information across internal "party lines," if
>you will. We're preparing training documentation about
>what's changing in a known (not by us) but undocumented system. This
>project is absolutely mission-critical to the company.
>The signoff parties are NOT our users. The SMEs can't
>see the forest for the trees (more than usual). We've
>got people telling us to MAKE THOSE OTHER PEOPLE UNDERSTAND.
>I'll get to report back to the VP about our success next week, after
>the pilot class. We started this project last week. In three
>weeks, we'll have trained 1000 people (stand up, in person)
>and we'll be done.
Lemme get this straight, here. You've got software. It's
not documented, but everybody knows how to use it who needs
to. The software is changing, so you need to train the users
in the new stuff. Am I right so far???
Now, you got a bunch of SMEs who are telling you what needs
to be trained on, but they're not the users of the software
and what they're telling you isn't quite what you think the
>up worrying about how to deliver what our users need,
>not what the SMEs think the users want, without inciting
>complaints about unresponsiveness. I woke up wondering
>if I'd completely missed the point, or if it really was
>simpler than it had looked. I woke up wondering if technical
>feasibility would line up with business requirements before
>the pilot class.
So, the SMEs think it's easier than it looks to you? But
you admit that you're not familiar with the system.
Well, maybe the SMEs are right? Maybe the user knows the
system better than you think?
Then again, maybe the SMEs are all wet.
If you could go back in time, I'd tell you that step
one is to conduct a training needs analysis. (OH, where
have I heard this before??? *Ask the user!*) Find out
what they know, what they need to know, how they use
what they know... Then you'd be a lot more comfortable
with what you need to develop.
But you didn't do that. So. Believe the SME??? Too
hard to swallow???
Can you take 15 minutes to call a couple of users???
Develop a quick 10 questions about what they're doing...
something that'll give you a good feel for what they
do and their level of expertise? Couldn't hurt. Might
make you feel better about what the SMEs say, or *could*
give you the amo you need to do things your way.
>I argued for 15 minutes this morning
>about the difference between using "correct" terminology,
>using what our users expect, or using what they'll need to
>learn. I worry about completing the training and having the
>whole system change. I worry about completing the training
>and discovering that we've overlooked something fundamental.
Is what they *need to learn* different from *correct*????
Why??? How do you know this? I don't think you'll ever go
wrong using "correct" terminology -- provide a glossary --
do a terminology overview at the beginning, transition from
the expected to the correct.
Of course, the meta message here is that you have no control
over the project and you have standards of quality that the
SMEs don't come close to living up to -- that and the
political stuff are getting in the way of your effectiveness
<she cuts to the quick>.
Scenario #1 -- Do it the SMEs way. The training succeeds.
You worried for nothing.
Scenario #2 -- Do it the SMEs way. The training fails.
But you, in your infinite wisdom, documented the SME's
input to the letter, so when somebody asks you what went
wrong, you point the finger... You do the CYA thing now
and gain credibility for the future. Only the user gets
short-changed. But, because you've gained a little
credibility in the process, you'll do better by them
next time. Besides, they learned the old system on
Scenario #3 -- Do it your way. The training succeeds.
You gain credibility, you feel good, the users profit.
But you can never turn your back on a SME again. Bad
working relationships -- ohoh! Better hope the SMEs
never gain control of your performance review!
Scenario #4 -- Do it your way. The training fails.
You send your resume to the first six ads in the
local newspaper and cross your fingers that one of
them responds. Nobody's happy.
We've all been in this situation once or twice. It's
pride and politics ;-) -- you gotta swallow your
pride and play politics. Hurts like hell! Makes you
mad! You *know* what you're doing! Why won't they
listen? Where's the buy-in to your professional
Sometimes you gotta emphasize the professional and
downplay the expertise. Fact o' life. Hate it, but
it's true. If you hang in there, gain respect, gain
credibility, eventually the user will profit. If you
walk, they'll find someone who'll shut-up-and-write
and the users will never get any better than they
One tough choice to have to make. No doubt about it.
sgallagher -at- expersoft -dot- com