Re: Thoughts on Working With Developers (long)

Subject: Re: Thoughts on Working With Developers (long)
From: SEnglish -at- MICROS -dot- COM
Date: Mon, 5 Apr 1999 12:47:45 -0400

I read with interest the thread on trying to get busy SMEs to do tech
edits that focus on content, and I have a question for the list:

Have any of you have ever taught your SMEs *how* to do a tech edit?

I thought so. Kudos to all two of you who said yes. If you are like
most writers, you assume that someone taught these people to do tech
edits before you met them. If they are like most SMEs, you are wrong.
I would like to share my experience with tech editors at a little
company on the banks of the Patuxent...

English's Theory of SMEs #1: Developers are people who like to think
of themselves as highly competent solution providers. If they didn't
need and enjoy control over their job content, they would have majored
in Sociology. It makes them nervous and uncomfortable to be tasked
with something they don't really know how to do. This in turn makes
them reluctant to do it.

When I was working on a long-term project with a group of mostly new
SMEs, I held a lunch conference on the topic, "How to Do Tech Edits".
I reserved the conference room for noon and told the developers and QA
people to bring their lunches, and I would provide dessert. I expected
5 or 6 people to sign up. I got 17.

English's Theory of SMEs #2: Developers are like bears-- they move
slowly, have sharp teeth and claws, and snarl a lot, but are powerless
to resist honey. I tried to avoid serving something lame like punch
and cookies. Fortunately momma taught me a little about baking. I get
my best results from strawberry shortcake.

After the bears shuffled into the room, took their seats, and finished
making fun of each other's lunch choices, I said, "Let's start off
with a little exercise. Let's do a technical edit of the following
paragraph. Call out any errors you find, and I'll circle them with a
red pen. John, you keep count of how many we find." I then used the
overhead projector to display a paragraph similar to the following
(technical terms changed here to protect the guilty):

"Their are too weighs to framjistam the beniculator usiing a 3700 pod
bays; begins the framjistam using a bleak grey pony (well brushed, or
artickyoolate sum of this beniculators with, a careful approaches to
languorous amour;"

We then went around the room pointing out mistakes in the paragraph.
If I was actually using the example above, I could count on the
developers to come up with anywhere from ten to fourteen errors. Then
I dropped the bomb.

"Thank you. These are all good observations. They are also all wrong,
because this was a trick question, for which I humbly apologize. But
when we began, I said, 'let's do a TECHNICAL edit'. From a technical
edit standpoint, there are only two mistakes in this paragraph, and
none of you mentioned them. There are actually three ways to
framjistam the beniculator, not two. So this documentation is
incomplete. And 3700s don't use pod bays, they use docking ports. So
this documentation is inaccurate."

In the deafening silence that ensued, I went on to make the following
points:

- All of the mistakes they pointed out could have been found and
corrected by any of the other writers; that's not what we need
technical editors for.

- Technical editors have valuable product knowledge that we can't find
anywhere else. They should focus on their special knowledge of the
product or process. They should provide those insights that we
couldn't get from just anybody.

- Technical edits should address two and a half issues:

1. Is it complete? Has anything been omitted or glossed over?
2. Is it accurate? Are there any obvious lies?
3. (half issue) Is it easy to understand? Will someone without your
in-depth knowledge be able to follow this?

- On the half-issue of readability and comprehension, it is enough to
be specific without being prescriptive. In other words, it is OK to
say that a passage is hard to follow, without suggesting a remedy.

- Technical editors are welcome to point out mistakes in grammar,
usage, spelling, punctuation, etc., if they wish. But the writers feel
that's not the primary editing mission-- that it's a waste of the SMEs
valuable time, and is a service available elsewhere. English's Theory
of SMEs #3: All developers believe they are grossly underpaid, while
at the same time believing they are paid far too much to do anything
but write or test code. Pander to this conceit.

- Focusing solely on the two-and-a-half issues above, while ignoring
other mistakes, should allow SMEs to get through an edit much more
quickly. If the SMEs think you will reduce their workload, you will
have the satisfaction of watching jaws drop all around the table, and
the pleasure of having made a roomful of new friends.

- Format doesn't matter. Editors can make changes to an online copy,
or they can write on a printed copy, or they can email a list of
specific changes. They can ask for an interview, in which they talk
and the writer takes notes. They can perform an edit in any format
they're comfortable with. If your doc group has processes or forms
that editors are required to use, think seriously about eliminating
these. Making your SMEs jump through hoops to do an edit in the
"proper" format may save you a few minutes when you (finally) get the
edit, but it gives them one more excuse to be reluctant to help you.

- Any editing schedule or deadline you commit to is fine with us.
English's Theory of SMEs #4: Finding time in the development schedule
for tech edits is not the SME's responsibility, and should not be a
point of contention between SME and writer. Somewhere up the food
chain there is a poor unfortunate who is responsible for seeing the
project delivered, complete and on time. If the SME tells you, "I can
have this tech edit completed one week after the ship date", AGREE to
that. Then send an email to the SME, thanking him or her for their
time, and restating the commitment. Tell them that based on this, you
will have the documentation ready XX weeks after the ship date. Be
sincere, friendly, and polite, and send a copy to your manager, the
SME's manager, and the unfortunate project manager. If they find this
schedule acceptable, you should, too. If they don't, it is up to them
to rearrange the SME's priorities to allow timely edits. English's
Theory of SMEs #5: SMEs and writers are sometimes like pit bulls in a
dog-fighting ring: instead of going for each other's throats, they
might be better off turning on their masters.

- (Speaking of pit bulls), the best tech editors I've worked with are
the ones who aren't afraid to be vicious. If I want a feeling of
protective, artistic, emotional ownership over something, I will take
up modern interpretive dance on my own time. This documentation is a
product that you and I are manufacturing. Be brutal. Any criticism you
write is a favor to me. Even if I don't agree with you, it will pull
me out of my comfortable little mindset and make me think. Anything
you find for me to fix now makes me look better upon final release.


I got good results from this approach. The quality and punctuality of
tech edits went up as SMEs stopped focusing on my creative use of
punctuation, etc., and they were happy in the belief that I had
simplified and shortened the task. Some of them are still my friends,
despite that incident the night of the release party involving the
sommelier, the fountain, and the three goats. But this post is long
enough already without going into that.

Steve English,
MICROS Systems, Inc.

Yes, that's really my name, and just to complicate life, my middle
initial is "M". My comments are my own. My company rarely understands
what I have to say anyway.

From ??? -at- ??? Sun Jan 00 00:00:00 0000=




Previous by Author: Re: Preference: One Big Manual or a Bunch of Smaller Ones?
Next by Author: Re: Dynamic HTML question
Previous by Thread: Re: FWD: Contracting Experiences
Next by Thread: Re: Thoughts on Working With Developers (long)


What this post helpful? Share it with friends and colleagues:


Sponsored Ads