Newsletter

Issue 24, 7 October 1999

ISSN 1442-8652

Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com

In this issue...

Feature article: Training subject-matter experts to review (edit) documents
Final installment: Collecting your e-mail when travelling (Part 4)
Defining the role of the technical editor
Subscription information

---

Feature article: Training subject-matter experts to review (edit) documents

Editor's note: This article began life as a note to the Technical Writers' discussion list (TECHWR-L) on 5 April 1999, and is reprinted here with the permission of the author, Steve English ( SEnglish@MICROS.COM ). Please note that Steve is using the phrase "tech edit" to describe what I would call a "tech review," but I think the issue he raises, and the solution he's found, are relevant to many editors' work.

I read with interest the thread on trying to get busy SMEs (subject matter experts) 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.

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 ... But this post is long enough already without going into that.

---

Final installment: Collecting your e-mail when travelling (Part 4)

The first part of this article appeared in Issue 21 of this newsletter, 26 August 1999: http://www.jeanweber.com/news/tenews21.htm#feature21

The second part appeared in Issue 22, 9 September 1999: http://www.jeanweber.com/news/tenews22.htm#feature22

The third part appeared in Issue 23, 23 September 1999: http://www.jeanweber.com/news/tenews23.htm#feature23

This article covers:

• Collecting your e-mail using a public-access internet connection

In some cases, public-access terminals only cater for Web- based e-mail access. In other cases, you can collect mail from POP3 accounts as described in this section.

To collect your e-mail, you need to follow the same steps as described in "Collecting your e-mail using someone else's computer" in parts 2 and 3 of this series, with two exceptions:

• You may find it easier and faster to change existing account information (which is probably the name of the last person to use this machine).
   
  
• These machines are usually on a permanent Internet connection, so you don't have to dial up a telephone number.

Here are the steps:

1. Change existing account information to yours.
2. Collect and send mail as usual.
3. Delete your account information.

Step 1. Change existing account information to yours

A public-access terminal might be set up to accept your user information on a form that is different from the ones supplied with the usual e-mail readers. If that is the case, use whatever form is presented to you. Otherwise, here are the instructions for filling your information into an existing account (probably set up as "Guest" or a similar name), using Netscape Communicator, Outlook Express or Eudora Light.

Changing an existing account in Netscape Communicator 4.5

1. Open Netscape Communicator.
    
   
2. On the Edit menu, click Preferences.
    
   
3. On the Identity page of the Preferences, fill in your name, e-mail address and reply-to address.
    
   
4. On the Mail Servers page:
    
   
   • Fill in your outgoing mail server information.
      
     
   • Click Edit to display the Mail Server Properties page, where you fill in your incoming mail server information.
      
     
   • Click OK to return to the Mail Servers page.

Changing an existing account in Outlook Express 98

1. On the Tools menu, click Accounts.
    
   
2. On the Mail page of the Internet Accounts dialog, choose an existing account name and click the Properties button.
    
   
3. On the Servers tab of the Account Properties dialog, change the incoming mail server names and the logon account name to yours.

Changing an existing account in Eudora Light 3.0

1. On the Tools menu, click Options.
    
   
2. Click the Personal Info and Hosts icons in the left-hand pane and change the settings to the ones you recorded from your setup at home.

---

Defining the role of the technical editor

Moved to http://www.jeanweber.com/about/responsi.htm.

---

© Copyright 1999, Jean Hollis Weber. All rights reserved.

You may forward this newsletter (in whole or in part) to friends and colleagues, as long as you retain this copyright and subscription information, and do not charge any fee.

Subscription information

This newsletter is no longer being published.

Privacy statement

I do not sell, rent, or give my mailing list to anyone.

---