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: SMEs and me (long) + a question From:"Rock, Megan" <Megan -dot- Rock -at- fanucrobotics -dot- com> To:TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 6 Jul 2000 09:37:50 -0400
Sierra Godfrey wrote:
> How often do SMEs give you their write-up of a manual, or at
> least the information, before you start on your work? Would
> you say that this is a common thing to happen?
Where I work, SMEs are required to fill out a documentation section in their
design specs. It's part of the template. The documentation section is
basically a few sets of questions (some are as basic as "What is the
official name of this feature and has it been approved by the Naming
Committee?") that help the SME to provide initial information for the
writers in a standard format. This can be effective if the SME actually
takes the time to fill out the template. Often times they simply refuse to
do it, so we end up working from their design specs without the
documentation section. This gives us something to go on, and we can usually
put together a rough draft to use as a basis for interviewing the SME and
gleaning additional information. Other times we're able to give them a
section from an existing manual and have them mark that up as a starting
point for the new version of the documentation.
> If you do have experience with SMEs giving you their
> information in what they think is a manual (or other output)
> format, how much liberty do you take to change it into
> readable and digestible information (what we all are trained
> to do as technical writers)?
Most of the SMEs know that we're responsible for documentation even if they
write the beta manuals for the beta testing or basic manuals for demos. I
recently worked on a manual that an SME had done in Word. It looked
wonderful, but as I started to study the content, I found that a lot of
valuable and necessary information was missing. The manual he had written
was almost entirely procedures with no information telling the user when or
why to use the procedures. I rebuilt the manual in Interleaf and started
filling in the gaps. The SME didn't have a problem with me doing this,
because he wanted to make sure the manual met our house style and contained
the kinds of information we typically provide to our users.
> And while we're at it, how often do you have the problem of
> just being about to send the manual off to the printer and
> then being told you can't because there are so many changs to
> be made suddenly by the SME? What do you do other than stress out?
This happens to us on a regular basis. Other folks who have responded to
your message suggested that you have the SME do a final review and sign off
on the manual before you send it to print. That is how we do it here, but
that still doesn't prevent last-minute changes. On 6/26 an SME signed off
on a particular manual, and I started the production process. On 6/30 I
gave our documentation coordinator a production-ready copy of the manual for
her final page-through prior to sending the manual to print. It was due to
be released in BaaN tomorrow, but this morning the SME came to me and said
that we need to add an entirely new section to the manual. Apparently
another engineer got ahold of an older draft and found things missing that
he thinks need to be included. So now I'm expecting to get all of their
changes by 7/19 (the engineer is on vacation next week, so we have to wait
for him to get back before he'll have time to finish reviewing the manual),
and we'll project another release date then.
I still get frustrated when we have last-minute changes like this,
especially when the SME has already signed off on the "technical accuracy
and completeness" of the manual, but I don't stress about it much anymore.
As long as I've done my part and have met my deadlines, I just make it clear
to everyone involved that the date is slipping again because the SME wants
to make additional changes, and I let it go at that.
I usually send a non-combative e-mail to everyone involved and very
matter-of-factly let them know that the release date has changed again and
Our problem is that after the SME has signed off on the manual, engineers
from other segments within the company find out that we're doing the manual
and ask to see a copy of it. Then we end up with several people who want
last-minute changes. With 200-300 developers/engineers/technical experts,
it can be a challenge to identify who should review the manual. We usually
leave it up to the primary SME we're working with to decide who else should
review a copy of the manual before sign-off, but sometimes people get left
out accidentally or find out very late in the process. We haven't figured
out the best way to handle this. We'd have fewer last-minute changes if
everybody who thought they should review the manual had a chance to look at
it before we go to production. Does anybody have any suggestions??
Megan E. Rock
megan -dot- rock -at- fanucrobotics -dot- com
All views expressed are entirely my own and are not necessarily shared
by my friends, co-workers, or employer.