by Kelly Schrank

[Note: I wrote a very detailed 14-page conference report for my employer. I then abstracted that report and published a 5-page article in Newsbrief, the Mid-South Chapter’s newsletter. What appears here is a belated collection of highlights from that newsletter article.]

The Technical Communication Summit, STC’s 54th Annual Conference, was held May 12–16, 2007, in Minneapolis, Minnesota. Around 1,400 people attended the annual STC conference this year.

[…]

My first session was “Estimating and Tracking Project Costs for Financial Success” with Joyce E. Lasecke. I thought this was a good session, very structured with good handouts that make it easy to go back through later and re-learn the concepts. Her presentation had two distinct parts: how to estimate and how to track. She very methodically began the part on how to estimate by outlining the three ingredients to a project estimate: (1) metrics, (2) assumptions, and (3) risk assessments. She then defined those and showed how to use them to your advantage. She went over the case study provided, which seemed to me to be a good example of a project estimate. The part on tracking was also good, with insights for how to start and what to do when you get off track. A good session, especially if project management is part of your job.

My second session was “Effective Page Layout for the Non-Artist” with Jean-Luc Doumont. Jean-Luc was an excellent presenter, very organized and very entertaining. He believes that page layout is about revealing the structure of the document visually. Unlike some people who think that a pretty layout and fancy graphics will bring the reader’s attention to the text, he believes that people will pay attention to the graphics and ignore the text. He also characterized a page as having two dimensions: vertical and horizontal. He believes documents need much more white space than most people allow. He likes big top margins and big left margins. “Space is a luxury.” This is where it became obvious to me that his ideas on design could be a bit “creative” for most technical communicators. His examples are full of white space and seem (to me) to be much more the work of marketing than documentation though I liked the look of them. All in all, an informative and fun session with lots of takeaway ideas.

[…]

My fourth session was “If I’d Known Then What I Know Now – Lessons Learned and Best Practices.” This was a lively and informative panel of speakers. Each discussed a lesson learned in their career and a trend in the technical communication industry. One of the funniest things to come out of this panel (from Bobo Vatovec): “The most common language in the world is Bad English”. A lot of their lessons learned and trend advice was tough to swallow: technical editors being told to lower their level of quality, tech writers being told to spread their wings and move away from our tech pubs departments? But these are experienced technical communicators doing a variety of different things in the industry for big companies and their own companies, so we should at least listen to what they have to say…

My fifth session was “Copymarking, Clarity, and More: Progressions of STC’s Technical Editing Community.” I went to three different tables to learn about three different topics:

1. The first was “Growing and Managing a Formal Editing Process” with Lisa Adair. Lisa is a technical editor for Rockwell Automation, a company that is revamping their whole tech pubs process. Their new system is topic-oriented, not publication-oriented; writers own a section of information, as opposed to documents. Their formal editing process began with a task force that worked on updating the company style guide. They began by picking a secondary style guide, and put topics in the company style guide where the editors veered from the secondary style guide or where the secondary style guide didn’t address something specific to their company. Another instrumental part of their formal editing process was to establish the levels of edit and create an editor’s checklist. The metrics they created in the level of edits document allow them to quantify their job. This was an interesting session for those in big companies that may have many editors, but it emphasized to me the need for an editor’s checklist and to be estimating my work.

2. The second was “Make Every Technical Editing Minute Count” with Jackie Eldridge. Jackie is a very experienced editor who put together a thorough and helpful handout for this progression. To understand the project, she suggested you first find out the purpose of the document from the author. Make sure the introduction material covers this, and that steps are in a logical sequence to that end. To understand the author’s expectation of you, she suggested that you use your editing checklist as a menu: talk to the author about which of these are most important to them. Advantages to knowing the author include being able to look for their trouble spots and fixing those so they do not embarrass them. Generic editing advice included: looking for the three “in”s: inconsistencies, inaccuracies, and incompleteness; making sure there is a source for information presented; and using different colors for different types of edits. I found this session helpful in not only proving what I already know to be correct, but also in offering some different ways of thinking about the process.

3. The third was “Concision and Clarity” with Susan Ledford. Susan is a technical writer and editor with experience in localization issues. She offered four reasons to pursue word reduction: (1) decreases costs, (2) increases readability, (3) increases usability, and (4) supports re-usability and single sourcing. In localization, word reduction is a directly measurable reduction in costs, as those excess words don’t have to be translated. For publications that are printed, shorter documents cost less to print. In addition, there is less to maintain when you reduce documentation length. In single-sourcing situations, the difference is exponential. From a usability standpoint, if there is less to read, readers are more likely to read it. She advises to do the following: (1) Use the search function to help you delete worthless words, (2) Create checklists of the type of words to commonly reduce, and (3) Rephrase sentences and paragraphs and reduce them to “content chunks.”

[…]

My eighth session was “Out of the Solitudes: Progressions of STC’s Lone Writer Community.” I went to three different tables to learn and talk about three different topics:

1.The first was “Preserving Sanity as a Lone Writer” with Dana F. Utz. The sole writer in his department for the last 8 years, Dana believes you should impose structure on your work through a “styles and standards guide.” He also suggests acting as if you are a part of a department in how you approach your work by documenting your tasks in a policies and procedures guide and tracking project time and milestones. He had a very nice handout of the presentation.

2.The second was “Editing Your Own Work” with Jerry D. Franklin. As a freelance high-tech marketing copywriter, Jerry must edit his own work on a regular basis. He offers six suggestions for editing your own work: (1) Take time away from the project to gain your objectivity (distance), (2) Put on your proofreader persona, (3) Use other style guides, (4) Create a style guide and document templates in advance, (5) Get non-SME reviewers on your team (customer service, tech support, marketing), (6) See if you can get a student to proof for the experience.

3.The third was “No Longer Alone” with Christopher Thiessen. Chris was an engaging speaker, very much interested in our own experiences and having us share them. He offered advice for people with specific questions and concerns. Like many of the other editing speakers, he suggested creating a style guide to ease the transition from working alone to working with others, and he suggested creating a list of commonly used words and their preferred usage.

[…]

The conference materials are available on the website. They are organized by presenter, so if you want the materials for any of the sessions I described, you should have an easy time finding them.

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.

What’s in a name? A lot. As technical editors, we know the importance of ensuring that the text we edit is clear. If we are performing developmental editing or copy (language) editing, we know that concepts must be expressed in such a way that the reader does not have to stop and figure out what is being said. We know that the more times a reader has to stop in a text to figure something out, the less the chance that the reader will leave the text with a solid understanding.

There are many elements to look for when editing a text at the development level or language level. One of these elements is terminology. The precise use of terminology is important. The more precise the terms, the more economical and efficient the text (Strunk and White, anyone?). The precise use of terms keeps text uncluttered and makes language more interesting to read and, in some cases, more valuable: the precise use of terms can make a text pregnant with meaning.

All of this, of course, applies to technical terms as well. Sometimes technical terms are misused. Other times a concept or model outgrows the original terms that were used to describe it. This is the case with the terms paper-based documentation and online documentation. These terms have been established in the technical-communication lexicon for years. The logic of their meaning was clear at the time that they emerged in the 1980s and early 90s: in addition to the centuries-old paper document, we also now had documentation on a computer (online). But these terms came into existence before the World Wide Web became dominant and hypertext became the norm for online documents, therefore eschewing the traditional linear, narrative structure.

In the days when text-based interfaces still existed, online documentation was much like paper-based documentation: it had a linear, narrative structure with traditional cross-references that did not lead a reader off on an entirely different path from the original text. At the time, it made sense to use the terms paper-based documentation and online documentation, because the only difference between the two was in their output: one was on paper, and the other was on a computer.

In the 1990s, the World Wide Web became a huge presence in the world of documentation. Because of hyperlinks, the term online documentation began to primarily mean a document that was not necessarily read in linear fashion. The term began to refer to the structure of a document, rather than the medium in which it was published. But the newer, predominant definition of online documentation conflicted with the older definition, which still existed.

These conflicting definitions have opened up a can of worms. Is it online documentation only if it has a hyperlinked structure? Is it online documentation if it is a document designed for print but posted to a Web site as a PDF document? Then there’s the quandary of whether a Web site that is printed out on paper is paper-based documentation or still online documentation.

From this confusion emerges the idea that perhaps it is not best to define a document by its published form. Perhaps it would be better to define a document by its structure—linear documentation or Web-based documentation. If you publish a traditional report on paper or post it to a Web site as a PDF document, it still has a linear structure. Even if you print an HTML document published on a Web site, that document still has a Web structure with hyperlinks, and the author’s intention is that readers will carve out their own narrative (logical) path. One could argue that the Web-based structure of the document is no longer present once it has been printed on paper, since you can’t click a hyperlink on a piece of paper. This is why I have included the author’s intention as part of the definition; if the author intends for readers to carve out their own narrative path, then the document still possesses a Web-based structure. And I argue that this contrasts with a traditional text that has many footnotes. The author of such a text intends for the reader to read in a primarily linear fashion, even if that reader skips ahead to other chapters. The text is still linear.

As technical editors and as members of a technical communication society, we may never be able to turn the tide of usage in the general business community. However, we should strive to use the most accurate terminology, at least within our own profession and communities. Electrical engineers strive to use the most precise terms in their field because it makes their communication more efficient. As technical editors and communicators, we must ensure that such precise language is used in all disciplines in which our work is based.

It is time to change the terms used to describe the different models of documentation. No more paper-based and online. It’s time for linear documentation and Web-based documentation. We as technical editors with our proverbial red pens have the power to help steer this change.

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

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

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.