A discussion list summary article, by 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:
1.
2.

OR

[conceptual overview]

Use the following procedure to add a new employee:
1.
2.

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.

By Justin Baker, Senior Member

Reprinted from “Capital Letter,” the newsletter of the Washington, D.C. chapter of STC, by permission of author and editor.

When I was a young technical editor, I was confused by all of the technical editing stages within one editing model—not to mention the competing editing models. Everywhere I turned, there seemed to be a competing name and a competing label for a particular aspect of editing. For example, substantive editing means developmental editing unless you are thinking of a particular editing model.

I was like a movie character in one of those old clichéd film montages where the character walks past one blinking neon sign after another, completely perplexed. To this day, I still do not adhere mentally to The Levels of Edit ¹ with its nine editing levels. I have sought to develop my own editing model based on my experience as a technical editor. Some theoretical physicists believe that the underlying formula that explains the theory of everything in the universe will turn out to be a simple, elegant formula. Life is indeed complex, but at the mountaintop of knowledge, things must have a simplicity that is understood by all. I believe that to be true of the levels of edit.

If some editors are not clear on the levels of edit that it takes to edit a document, then most managers are certainly not clear on the levels of edit, either. As we all know, communicating our profession’s conceptual models to managers is very difficult. Most managers (excluding technical communication managers) think of writing and editing as a black box activity. They see the document go in; they see the document come out. Most managers are blissfully ignorant of the complexities of our job. Their blissful ignorance may be partly our fault. Perhaps we have not communicated the nature of our activities in the simplest possible way.

This is a usability issue. We as technical communicators are focused on usability more and more, so when the conceptual models in our own profession are not easily understandable, then we need to simplify them. I think it is time to simplify and re-label the editing levels so that they are straightforward and intuitive, at least at the top level. The Levels of Edit espouse no less than nine editing levels, and labels for some of these editing levels are surely not intuitive to either some editors or managers. Let’s simplify the editing model down to three editing levels at the very top.

Knowledge Editing
I propose that the first editing level be titled knowledge editing. Knowledge editing refers to the technical subject matter in a document, both in text form as well as in illustration form. In the editing model I propose, the knowledge editing level would be divided into four sub-levels:
• knowledge accuracy,
• knowledge completeness,
• knowledge logic,
• knowledge hierarchy.

The knowledge accuracy and knowledge completeness sub-levels would ensure that the subject matter is accurate and complete. The knowledge logic editing sub-level would ensure that the a-b-c logic of the subject matter is sound. The knowledge hierarchy editing sub-level would ensure that the 1.0, 1.1, 1.1.1 hierarchy of the subject matter is sensible. Of course, the editing sub-levels in this editing level might be performed at the same time as they might be in the proceeding editing levels.

Language Editing
I propose that the second editing level be titled language editing. Language editing refers to the technical subject matter in a document, both in text form as well as in illustration form. Language editing would focus on the manifestation of the knowledge through words and images. This level of editing would encompass the following editing sub-levels:
• sentence structure
• grammar, diction
• punctuation
• spelling
• character mechanics

For visual text, language editing refers to the particular standard visual elements used in any given type of illustration. For example, use case diagrams use particular industry-standard visual elements that must be used in the diagram; for network diagrams, some companies might want to consistently use the same network server icon. The language editing level would ensure that the text language as well as the visual language are standardized.

Layout Editing
I propose that the third editing level be titled layout editing. Layout editing focuses on the following editing sub-levels:
• standard, large-scale document structures
• text and illustration spacing
• large-scale font formatting
• miscellaneous layout mechanisms such as running headers, page numbers, and hyperlinks

Conclusion
In the editing-level conceptual model that I propose, I do not consider it necessary to build in a layer that prioritizes the levels of editing as is dictated in The Levels of Edit or a Council of Biology Editors (CBE) publication² from several years ago that proposed the reprioritization of the editing levels found in the Levels of Edit. Simplicity is best in this situation. It is enough to give technical editors the basic editing levels and sub-levels and let them decide what takes priority.

I have not covered all the possible nooks and crannies of the editing landscape in this brief column, but it doesn’t matter. Even if I had covered every single aspect of editing, there would be arguments about the arrangement of the editing levels and sub-levels. The point is that the editing conceptual model needs to be simplified at least at the top editing level. I say knowledge editing, language editing, and layout editing. You may say something else. And we can debate on the editing sub-levels that lay beneath. I’m merely making a call for clarity.

Justin Baker has been a technical writer and editor for nine years. You can reach him at bakerjustin@earthlink.net.

Endnotes
¹ Van Buren, Robert, and Mary Fran Buehler. The Levels of Edit, 2nd Ed. Pasadena: Jet Propulsion Laboratory California Institute of Technology, 1980.

 ² Nadziejka, David. 1999. Council of Biology Editors Guidelines, Number 4: Levels of Technical Editing. ISBN 0-914349-5-0. Reston, VA: Council of Biology Editors

On Tuesday, April 17th, the SIG hosted its first ever virtual SIG membership meeting, via a teleconference call-in number.  We invited only our SIG members, requested RSVPs for the 100 lines that we had reserved, and provided toll-free access to our US and Canada members.  (We are researching the costs of trying to provide toll-free access to our non-US members, so stay tuned.)

During this meeting, we made some announcements about news and happenings in the SIG and then we had a technical presentation from Sue Kocher, on Editing the User Interface.  We have archived the slides and materials in our Meetings Archive page, and we hope to post an mp3 recording of the meeting there after we receive it in a few weeks.

If you attended this call, or if you wanted to attend this call, we are interested in hearing what you thought about our first attempt at a virtual membership meeting!  Please post a comment to this blog post, and let us know if you have any comments, questions, ideas, etc about any portion of the membership meeting. 

by Ben Davies, STC Manitoba Program Chair

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

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.

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.

Here’s the latest reminder and announcement from the conference planning committee…. “If you snooze, you lose.”  Or so the saying goes.  Register today to save money and take advantage of the advance member rate of $795 (USD).  The deadline for advance registration is May 4. And don’t forget to make travel arrangements and accommodations.  Hotel reservations must be made by April 13.  All the information you need about the Conference and hotels is on www.stc.org/54thConf.

by Sue Kocher

Editor’s Note:
This article originally appeared in the February 19, 2007, edition of words@sas, a series of articles about Terminology Management issues, published on the internal web site of SAS Institute Inc.  It was originally reprinted in the Q1 2007 issue of Carolina Communique (http://stc-carolina.org/newsletter/tiki-index.php?page=Is+Consistency+Boring).  Now, it graciously appears in our own newsletter. Isn’t reuse grand? – Michelle Corbin

What do customers want from our software and documentation? They want to accomplish tasks, and to obtain information about tasks, as quickly and painlessly as possible. Do they also expect to be entertained along the way? No, not when there is work to be done. Years of usability analysis in the software industry indicates very clearly that clarity and ease-of-use is topmost on the minds of software users. Sure, software users appreciate a look and feel that is aesthetically pleasing, even beautiful. At the very least, they want a user interface design that says “quality.” Bells and whistles are nice, as long as they’re functional. But when it comes to getting work done, most of us wish that cute little animated PC would stop cartwheeling and get the heck out of the way when we jab the X!

A crucial key to the usability of both software interfaces and written material is consistency. The software industry is slowly realizing that technical information is far easier to digest and use if it is predictable. In fact, this is true of language processing generally: in order to understand speech or writing, the brain is constantly engaged in a rapid-fire testing process, predicting or “precomprehending” what is likely to come next, according to what has been understood already. Furthermore, most people read text not word by word, but in chunks. We learn to recognize the “shape” of printed phrases and sentences. That way we don’t have to stop and sound out each word in our heads, or ponder its meaning.

What we want to give our customers, so as not to unduly wear out their brains, is an experience with our products that includes enough “new” information to complete the task efficiently. For this, we must be consistent and predictable wherever possible.

The following examples of consistency issues focus on user documentation. However, the same principles apply to all “language resources,” including the text in user interfaces, in marketing materials, and even in e-mail communications.

Consistency in Documentation

Not so many years ago, technical writers and editors shared a set of assumptions about “good writing” that were mostly instilled by creative writing teachers, or by training in academic research writing. We realized, of course, that technical writing is more formal and straightforward than prose for art or entertainment, yet not as formal or wordy as the language of an academic paper. But we clung to some old habits.

We slowly gave up our inclination to use idiomatic speech, and of course we had to learn the lingo associated with software and particular products. We finally came to realize that there was no need to slavishly follow the old adage, “Say what you’re going to say, say it, and then say what you said” for the simple reason that most users do not read our documentation from start to finish in a serial manner.

But it was hard to dispel the feeling that repeating the same sentences and phrasing multiple times in a single document would be “boring” for our users. Writers sometimes protested that their creativity was being stifled if they were asked to express the same concept or task the same way each time, for the sake of consistency.

How Many Ways Can I Say “Do This”?

Suppose a User’s Guide includes instructions for completing a number of tasks in “Display mode.” In some legacy doc from the old days, you might see a nice, clear sentence like this:

To (do task A) in Display mode, complete the following steps:

But in the same chapter, you might also find these:

In Display mode, you can also (do task B) by completing the steps below.
 
Follow these steps to (do task C) in Display mode:

(Task D) can be accomplished in Display mode by working through the following procedure:

… and any of a myriad other possibilities. Does this make technical documentation “more interesting”? No, but it makes the tasks more exhausting and time-consuming to find and to learn, because the words in each sentence must be read and “parsed” carefully. Even more mental effort is required to understand that all of these sentences are saying the same thing, and that there is a pattern in this chapter for presenting task instructions.

Over the past few years, the SAS Publications Division has come a long way toward standardizing what and how we write. In addition to our comprehensive Style Guide for User Documentation, we now have templates for different types of books, so that users can predict what kind of content a book offers by its title. Developing standards for topic titles was a challenge that took over a year to complete, because everyone had their own “standards”, often well thought out, but that clashed with one another. Our documentation looked like it had been written by several different companies, with completely different ways of organizing and presenting information.

Now users can scan a Table of Contents or a list of search hits to quickly find the task or conceptual information that they need. As writers and editors learn to apply the guidelines, our user documentation continues to improve in clarity and searchability.

Being Creatively Consistent, and Consistently Creative

Imagine how much time, effort, and human resources can be saved by using “copy and paste” to recycle the same message. Imagine how much more smoothly our solutions will work together if they all use similar labels, messages, and designs—that’s intelligent reuse. Far from stifling creativity, the use of consistent phrasing frees writers and developers to focus their creative efforts on making complex concepts and tasks more “user friendly” and effective. Software is complex, because it accomplishes complex tasks for ever-changing markets. Our job is not to impress the user with how huge and dauntingly omnifunctional software is. Our job is to make complex tasks look easy, and to give the user lots of a-ha moments (Ah, I’ve done that before, I know what that means!) along the way.

[Editor’s Note: I received a request from Candy to post this call for participation for her thesis research.  Please contact Candy with any comments or questions (jenkins114@comcast.net).  — Michelle Corbin] 

Hello.  I am currently pursuing my Master’s Degree in English, with a concentration in Professional Writing and Editing, at George Mason University.  My thesis is titled “From Technical Writer to Professional Communicator: The Evolving Model of Documentation Departments within IT Companies.”  I will be examining Documentation or Tech Pubs Departments and Technical Communicators and how their role is changing and needs to continue to change in order to remain a viable entity in the future of the IT Industry.

As part of my thesis, I have developed a questionnaire for tech writers, specifically in the IT industry.  The questionnaire is a 5-page MS Word form, and it should only take about 15 minutes to complete.  The process is completely anonymous, and no names or company names will be used in the report.  Once you download and complete the form, simply return it to me at cjenkin5@gmu.edu.  Once the form is received, I will print a hard copy and delete the email, so no information can be connected with a particular email.

If you have any questions regarding completion of the questionnaire or need to contact me regarding any other matter, please feel free to contact me at jenkins114@comcast.net.

Click on the link below to access the web site containing the questionnaire.  Completed questionnaires must be received by April 20th.  Thank you in advance for helping me with my research.  I hope the results
will prove to be useful to Technical Communicators in providing insight on how to prove our value within our organizations.

http://home.comcast.net/~jenkins114/

Thank you,
Candy Jenkins
Documentation Manager
Northrop Grumman IT, Health Solutions