STC Summit 2007 Report

Virginia Janzig

I attended the STC Summit for the first time in about 10 years. In addition to being a presenter in the Editing Progression, I attended many of the sessions that were offered, and spent worthwhile time in the vendor showcase, especially the bookstore.

Three things stand out to me.

First, the organizers had clearly paid attention to the comments received about prior conferences. The  conference was more focused on writing and editing, and much less on tools. And the variety of different kinds of writing topics was tremendous: everything from processes and procedures and structured language to highly technical online documentation. Having recently taken a job in a courseware development group, an area about which I know very little, I was pleased to find more than one session on instructional design. The two I attended were quite helpful.

The editing progression had several presenters on a wide range of topics, and it was well attended. A couple of other sessions on language were also well attended and useful, as well as entertaining. And our language is nothing if not entertaining.

Second, several sessions on various topics provided information for both beginning and advanced writers. Assessing an audience and its needs is always a challenging task, but I think that the organizers and presenters did an excellent job of delivering to both ends of the spectrum.

Third, I was especially glad to see sessions on careers, not only what kinds of careers are available in the technical documentation arena, but also how to progress in a career: what opportunities to look for, how to build skills, and how to present yourself (not just your resume) in a professional and business-like manner.

The Minneapolis Convention Center was a great venue, and the city had a lot to offer. There were plenty of rooms for all of the sessions (although a few of the most popular were standing room only), and the vendor showcase area had refreshments and Internet access. The incredible walkways made it really easy to get from hotels to the convention center and to lots of other businesses.

In closing, I was pleased to see how many young people attended the conference. Clearly, technical documentation is perceived as a legitimate career and career path, and, if we can help persuade the U.S. Department of Labor to update its definition of this job, then I think that the STC and technical documentation as a whole will benefit, and the technical community will be well served.

Paper, Screen, or Scissors? Editing on Hard Copy or Soft Copy

Tim Slager

The question posted in our discussion list: Should editors edit on hard copy or soft copy? The answer: Yes. Or, it depends. Essentially it is not a matter of should; it is a matter of personal preference and what works best in different situations.
The exchange on the STC Technical Editing SIG discussion list in response to this question went on for several days and included 20 posts, which is higher than average for our moderate-traffic list. Apparently, we tend to be passionate about how we do what we do.

Hard Copy

On one side are those who print a copy and mark it up. Several people mentioned that they notice more errors when they edit hard-copy documents. Hard copy also has these advantages:

  • Easier to flip back and forth to compare for consistency
  • Very portable
  • Easier to see punctuation marks and spelling errors
  • Easier on the eyes
  • Less risk of computer-related stress injury for the editor
  • Easier to mark suggested moves of text
  • Often easier to see corrections in contrasting ink

But the tide is turning, even for those who prefer hard copy. Some people will compromise by marking up hard copy, and then scanning it to make a PDF file. One poster likes to edit hard copy and make changes in soft copy. Another marks up the hard copy and then transcribes comments to soft copy, both for legibility and to tone down “intemperate remarks” (on those rare occasions when one makes it onto paper).

Ultimately, it’s a matter of taste: an “online version of the document is helpful…but I still prefer to deliver markup on hard copy.” One poster still prefers “my trusty red pen.” Another suggests: “Perhaps that is in part due to eyesight issues and in part due to lifelong habits and learning modes.” Some prefer “a quieter, slower paced approach,” and believe it leads to better quality.

Soft Copy

Not everyone wants a slower paced approach, however. When there is a lot of work to be done, speed counts. For some, hard copy may be the preferred approach, but “time and cost considerations” take precedence and “in my current job, I work most often with soft copies.” Several noted that soft copy is faster, and time is money. “Online editing is a cost-saving measure,” said one poster “I can return a document for author review in nearly half the time it takes the other editors.”

The “flipping back and forth” in hard copy can be distracting to some. You might notice structural problems that, in some cases, are better left alone.

The tools that are available with a computer offer a big advantage to online editing. Several people noted that searching for repeated problems is easy with soft copy. One commented, “I’m sure I provide better edits now that I have access to PDF files” for searching. Change tracking tools can be troublesome at times but allow writers to view markups in much the same way they can with hard copy.

Certainly, for many of us soft-copy editing is a big part of our job responsibilities. In fact, later posts in the thread turned mostly to an exchange of advice for how to work with Adobe Acrobat, Word, and other online editing tools as well as with document management and version control software.

One editor took a job on the condition that she could “continue working… completely online.” She goes on to say, “I definitely prefer soft-copy edits, and will do a hard-copy edit only when specifically requested by the author.”

Another noted, “I’ll edit on hard copy if I have to, but I much prefer soft copy at this point.” I sense some ambivalence here, though: was there a change in preference? Someone else perceived that “younger team members do prefer soft copy; it seems they are more comfortable with the technique and it is quicker for them.”

There’s More Than One Way to Do Things

The person who observed the preference of younger editors for soft copy, counters by noting that “many others my age or older might still prefer hard copy.” Different people and different circumstances call for different approaches.

One editor summarizes it like this: “Both types of editing can yield acceptable results. As to preferences, different editors will give you different answers. I might give you a different answer at different times, depending on what I’m doing and how I’m feeling.”

Another says, “I think that both are acceptable….I prefer to edit hard copies when proofreading but I vastly prefer soft copies for comprehensive editing.”

This either-or view seems to characterize the variety in the larger community of editors. No one implies that their approach is the only one.

There seems to be a general, if at times reluctant, sense that the move is toward more online editing. One post states that the choice of software that is used for soft copy editing is pivotal, and that such tools keep improving. It concludes with, “I doubt that there was much serious copy editing going on at PC screens 20 years ago, but ten years from now doing it on paper might also be a relative rarity.”

The first response to the question of which method was better begins with what sounds like a hard-line opinion: “Editing hard copy is best.” But this same post ends with “I edit by reading hard copy and making changes in soft copy. That seems to combine the best of the choices. Hope this opinionated answer helps.”

In the end, it seems to be a split opinion.

General Impressions: “The Technical Editor as Diplomat…”

Michelle Corbin

I recently re-read the journal article “The Technical Editor as Diplomat: Linguistic Strategies for Balancing Clarity and Politeness” by Mackiewicz and Riley (Technical Communication, Volume 50, Number 1, February 2003, pp. 83-94(external link)).

This article discusses 8 different strategies, based on linguistics research, for balancing clarity and politeness when making editing comments, in the hopes of building and enhancing the author-editor relationship. Although I do not agree with all of the strategies and conclusions that the authors make, I did find it a fascinating article – one that made me actually think about and try to articulate my own thoughts on the role that politeness plays when I make my editing comments.

Although this is not a recently published article, I thought it might be nice to use it to kick off this new type of newsletter article in the Technical Editing SIG blog/newsletter. We receive so much information that it is difficult to know what to take the time to read, and the SIG is trying to help you make a decision as to whether to read an article or not – we want to entice and encourage you to read these articles (and who knows, maybe join a conversation about them on the blog or in our discussion list!).

Do you remember reading this article? Did this entice you into reading it (or re-reading it)? Do you have some thoughts about this article? Please consider sharing them on our blog or as part of our discussion list (I decided to cross-post this to both places, in hopes of encouraging cross-reading/cross-participation in our blog and discussion lists. (:biggrin:) ).

Understanding Passion Fluff

Ben Davies

For the past year, I’ve been a technical writer for an engineering-based company. As a result, I often deal with difficult-to-understand documents written by technical people. Without reading these documents, an outsider might assume they are complicated because they are filled with complex information; in reality, the documents are complicated because of the way they are written.

The following paragraph is an example of a paragraph that is very complicated because of the way it was written:

This key only activates radio buttons that are de-activated. Questions that need to be answered by activating the appropriate radio button are given multiple options (two or more). By default, one of the option radio buttons will be activated. If you would like to activate an option other than the one activated by default, move to the desired option radio button using the TAB key and press the SPACEBAR. This will activate the desired option radio button and deactivate the one activated by default. For example, when indicating the gender of the Applicant, you may want to activate the Female radio button. Since the Male radio button is activated by default, move to the Female radio button using the TAB key and press the SPACEBAR. This will activate the Female radio button and deactivate the Male radio button.

 

After reading this paragraph, the following question comes to mind: Is using radio buttons so complicated that you actually need to provide a detailed example?

I call such paragraphs “passion fluff”—text that someone has put a lot of time and effort into writing but that really say nothing.

The “fluff” in the example above is all the times the author re-iterates the same concept in different ways in an attempt to clarify an already convoluted set of instructions. The example itself is “fluff”, because using radio buttons isn’t complicated.

I decided to re-write this paragraph to see if I could take out the passion fluff and came up with the following:

Questions are answered by highlighting the radio button next to the appropriate answer.
To highlight a radio button, press the spacebar.
To move between radio buttons, press TAB.
Note: Only one radio button can be highlighted per question.

 

I had an epiphany last year when I realized people don’t like to read, especially when they are trying to complete a task. Therefore, essential information buried in long, convoluted paragraphs is useless. Most technical writers already know this, and I hope I’m preaching to the choir; however, many subject matter experts don’t know this, especially if they came from University where writing long (10+ lines), convoluted, academic-style paragraphs and sentences (like this one) are a way of life.

Contrary to popular belief, academic writing has no place in the business and technical world of documentation. Because of this, it is our job to teach passion fluff writers what is acceptable and what isn’t. Allowing someone to get away with passion fluff does two things: it lowers your expectations of the other person’s writing ability, and it encourages the other person to continue writing incorrectly.

Remember, though, that passion fluff is very difficult to deal with because of the passion that’s involved.

A strategy you could take to help passion fluff writers is to re-write something they’ve written to show the value of clear communication.

The goal of re-writing something isn’t to prove how badly they write, but to make them better writers. Show them what is right, rather than showing them how what they did was wrong.

Reprinted from Manuscript, the newsletter of the Manitoba chapter of STC, by permission of author and editor.

Introducing Procedures, a Discussion List Summary Article

Abby Kasper

As writers, we are constantly challenged to rethink our writing styles and improve the way we present information to global audiences. Recently, the following question stimulated an animated discussion in the discussion list community.
We are considering changing the style we use to introduce a procedure. Does anyone have thoughts about the pros and cons of either of the following styles:

[conceptual overview of a task; for example, adding new employees to a database]
To add a new employee:

OR

[conceptual overview]
Use the following procedure to add a new employee:

Most writers who responded to this query expressed a willingness to use both styles but preferred to introduce a procedure with an infinitive phrase. They then described how they use this style to address two important issues: creating documentation that is easy to translate and documenting procedures concisely.

Writing for Translation

Infinitive phrases have a valuable place in technical writing, but they must be used carefully. The infinitive phrase used by an English-speaking writer may be reduced to a single word when it is translated to another language. As a result, separating the word “to” from the verb associated with it can cause structural problems, so it is important to keep the components of an infinitive phrase together. For example, the following list would translate poorly:

Use this device to:

  • measure room temperature
  • detect intruders
  • generate an audible alarm

Writing Concisely

Using a short but descriptive infinitive phrase to introduce a procedure can reduce the word count of a document and provide visual cues that help the user locate the information required.

Introducing a procedure with an infinitive phrase can reduce the word count of a document by eliminating frequently used phrases such as “Use the following procedure.” Contextual clues (such as numbers) indicate that the user must perform an action, so the clarity of the instructions is not harmed.

To further enhance the clarity of a document, some writers create a heading for product overview information and also format the infinitive phrase as a heading. These visual cues quickly lead users to the information that is most useful to them. A user who needs basic conceptual information about a function of a product can read the overview information before beginning the procedure, and an experienced user trying to remember the first step of a procedure can easily skip the overview information and locate the procedural information.

Conclusion

In conclusion, most technical communicators who responded to this style question prefer to introduce procedures with carefully constructed infinitive phrases, but were willing to use descriptive, complete sentences if the audience needs justified that choice.