Author: Yoel Strimling

Posted on

Providing Value: STC Takes the Lead

Larry Kunz

Are you getting value for your investment in STC? Many members, as they renew their memberships for 2008, are asking what value they receive in return for the dues they pay.

I’m pretty well sold on the value of STC. Just last year I got a new job after spotting the opening on my chapter’s employment page. During the interview process, I benefited from the experience I’ve gained through STC and the contacts I’ve made in STC.

But that’s just one person’s experience. STC must offer real value, consistently and across the board, to members and prospective members. STC will need to offer even more value to remain competitive in the next few years.

(Yes, I said “STC” and “remain competitive” in the same sentence. STC is a business, and it confronts significant issues and stiff competition in today’s marketplace. It’s nice to think that STC is more than just a business and that it’ll always be here. But the reality is that, to remain viable in the short term, STC must do better at proving its value.)

Taking a longer view, however, STC has an opportunity to provide value in ways that go far beyond what’s possible today. STC is uniquely positioned to take the lead in defining the profession of technical communication. When we do that, we’ll provide significant and enduring value for our members, for practitioners who haven’t yet become members, for the people who employ us, and even for society in general.

Defining the Profession

Ever since I joined STC 25 years ago, we’ve been saying that technical communication is a profession. But we’re an immature profession, and as a result our work often isn’t taken seriously by the people who employ us and the people who buy our products.

To grow into a mature profession, we need at least two things:

  • An agreed-on code of ethics. STC has its own ethical code, but it doesn’t represent the consensus of the entire profession, and it’s not enforceable.
  • A unique body of knowledge, and the expectation that each practitioner has mastered that body of knowledge.

The technical communication profession is desperate for leadership – desperate for a set of ethical values, an agreed-on body of knowledge, and perhaps a credentialing system.

Today, all of the pieces are in place for us to develop technical communication into a mature profession. We have the will, we have the know-how, and we have an organization – STC – with the stature, the broad reach, and the resources to lead the way. STC can assemble the building blocks for our profession, it can forge consensus, and it can gain buy-in among the significant stakeholders in the worldwide community of technical communicators.

What Is STC Doing?

As a member of the STC board of directors I’m leading the effort to formulate a strategic plan, or roadmap that positions STC as the leader in defining the profession – especially by establishing a body of knowledge and promoting ethical standards. (We’ve already begun working on the body of knowledge.)

You might have heard the phrase telling our powerful story. The strategic plan focuses on raising the profile of all technical communicators – and emphasizing the value we provide to our employers and to the world in general – by marketing our people and the work we do.

The strategic plan also emphasizes establishing and expanding partnerships. By teaming with other organizations, STC will strengthen its leadership role in the profession and position itself to provide even more value to its members.

STC doesn’t need to be fixed. It needs to be modernized. The board of directors, along with the executive director and her staff, understand this. We know that STC must keep providing value over the short term while setting the stage for long-term value by defining the profession. We’re implementing plans to keep the business of STC strong by retaining and attracting members and by constantly reviewing its suite of programs and services to ensure that they still make sense.

I believe that we can find a way to develop technical communication as a profession and continue delivering real value to our members – all without losing the social and interpersonal aspects that have made STC so special to so many people over our history.

What It Means to You

Defining the profession will benefit every technical communicator because it’ll make us more valuable to the people who sign our paychecks. Instead of simply saying “I need some manuals and online helps” (which reduces technical communication to a commodity, not a profession), our employers will realize that they need professional people who contribute value to the organization by increasing customer satisfaction and making products easier to use – thus easier to sell.

We’ll prove our value on a much wider stage as well. By providing information that makes technology work for the people who use it, we contribute real value to society as a whole.

I’m running for second vice-president because nobody is better acquainted with the issues that STC will have to confront as leads the profession to where we want it to go. I can foster a climate of creativity and cooperation in which we’ll plot a course for the Society and the profession. STC needs leaders who can build consensus and explain decisions to the membership at large. I hope you’ll entrust me with your vote.

The next few years will be exciting. Along with my membership dues, I’ve chosen to invest my time and energy in being a part of this effort. I hope you’ll agree that STC’s future, and the value it’ll bring to you, is worth investing in as well.

Lawrence D. “Larry” Kunz, a candidate for STC second vice-president, is a member of the Society’s board of directors and immediate past president of the Carolina chapter. He is employed as a Senior Technical Writer at Systems Documentation, Inc., in Durham, NC, where he manages a large software documentation project. To learn more about Larry, check out http://lk81924.googlepages.com/home(external link).

Posted on

Editing DITA Topics: The Changing Role of the Technical Editor in the Age of DITA and Topic-Based Authoring

Michelle Carey, Michelle Corbin, and Shannon Rouiller

Can we live without books? Certainly, we can’t live without those wonderful novels that we pick up at the airport. But we can and should replace the book with a more useful vehicle to deliver technical information, and, as editors, we can learn to help create and edit the content for this new information delivery vehicle.
In the past, technical editors worried mostly about the meaning and appearance of the text in printed books or online help. We focused on margins, font sizes and types, line spacing, grammar, punctuation, and the clarity and organization of the text. However, much has changed in technical documentation. Although we never forget the importance of clear language and style, we have shifted much of our attention to a new paradigm: topic-based authoring.

With Darwin Information Typing Architecture (DITA) and topic-based authoring, we focus first on the external text that the users read, but we must also focus on the DITA XML elements and technology that are used to produce that external text. This new focus on DITA elements and technology has re-created the role of the technical editor in the age of topic-based authoring.

Learning the DITA XML elements and technology

Editors must now focus on the content in a different way and must also review the XML elements that writers use to create that content. DITA XML elements identify content for what it is, not for what it should look like. Editors must help writers use DITA elements properly because using the correct DITA elements can ensure that search engines return more precise results for searches or help users filter through lots of information. By understanding and using the tools and technology that produce the text, we can communicate more effectively with our writers. If we use the names of elements and attributes to explain the change that needs to be made to improve the text, writers are more likely to use elements consistently.

Editors must also work with authoring tool developers to ensure that DITA contains the most appropriate semantic elements and that the DITA elements generate the appropriate highlighting (bold, italic, monospace type, and so on). One of the current challenges for editors and writers is knowing what DITA element to use for which type of content. For example, DITA has an element called <apiname>, but should we use that element for all content about APIs, such as methods, classes, and packages? Separate elements do not exist for methods and classes. Editors can step in and ask the tool developers to create more specialized API elements, such as <apiMethod> and <apiClass>.

Editing topics

In addition to strong writing at the sentence level, an effective topic should meet certain criteria. Editors should look for:

  • A precise title
    One topic collection from one product might be displayed with other collections from other products. Therefore, topic titles must often be more precise to distinguish them from other similar information. For example, many software products have information about security. You cannot simply title those topics “Security.” A better title might be “Database security” or “Configuring ACLs for database security.”
  • Useful content
    At IBM, editors try to ensure that topics are not used simply as navigation devices, but that they contain some useful content. Also, we ensure that each topic’s content is independent of other topics.
  • One or more links to other topics
    Users should never be stranded in a topic. You can use linking, indexes, and tables of contents to ensure that users get to the right information quickly and easily.

 

Editing topic collections versus books

Users of software and hardware products typically require the right information at the right time. Users no longer sit in their living rooms next to the fire and read the manual. They want easy to read, useful information that will help them complete some task right now. To accommodate our users’ expectations, we must create self-contained, reusable topics that can be packaged in small or large collections.

In addition to editing a topic, we must also edit collections of topics. Editing topic collections is not the same as editing book chapters. What’s changed for editors is that many of us rarely edit books as linear sets of information. We don’t look at how one chapter flows to another or how chapters build on previous chapters. We also no longer assume that users read the first chapter and work their way to the final chapter. For example, many technical manuals use transitions such as “The previous chapter showed you how to create profiles. This chapter focuses on editing profiles.” Such a transition never makes sense in a set of topics because we cannot assume that users read linearly or arrived at the topic through some predefined sequence. What topic writers might use instead of the transition is an imperative to the user to do a prerequisite task of, say, creating profiles. However, the topic writer cannot assume that users have read the topic about creating profiles.

Think of topics as buoys floating in a sea. The buoys are connected to other buoys, but not necessarily in any particular order. Books are typically written as if they were train cars connected linearly. We don’t want to make users get on the train and have to walk through each train car to find the right nugget of information. The editor’s job is to ensure that we provide the buoys, or topics, that users need and that the buoys are easy to find. Also, users must be able to jump from one buoy to the next whenever they need to.

To make topics easy to find in the collections, editors need to help arrange topic collections and topics within collections in ways that make the most sense to users. For example, topic collections might be organized by product or by user goals (such as administering or troubleshooting).

Picking our battles: Focus on the rules

When you are struggling to convert libraries to topics and reorganize a mountain of information, smaller things such as whether a list is compact can seem much less important to you. White space, font choices, widows, orphans, and transitions don’t matter as much in an online, topic-based world. You find that you can let go of many of your old pet peeves, and that can be liberating.

Although we were able to let go of many pet peeves, we found that others needed to be championed. In cases where DITA doesn’t provide what we need, editors must play a key role as the advocates for needed changes to DITA. We can submit requirements to DITA, or find workarounds, or sometimes both. At first, we were tempted to submit requirements for all sorts of esoteric issues. We soon found that without a business case, requirements were not going to be accepted. We quickly learned to pick our battles and submit requirements only when prudent.

For example, we submitted a requirement to add a new element inside the <steps> element for task topics. No element was available for the “To” statement to introduce a set of steps. For purposes of clarity and reinforcement, we want to introduce steps with a statement that indicates what the steps are for, such as “To print the report:”. But there is no place to put the “To” statement so that it can be part of the <steps> element. Because we were not willing to wait for that requirement to be addressed, we came up with a workaround to add the “To” statement as the last paragraph of the <context> element in the task topic. We don’t like the workaround because it separates the “To” statement from the list of steps, and therefore does not support clean reuse of the <steps> element. But we had to do something in the interim while we waited for the requirement to be addressed.

Short descriptions: Focus on the content

Change of focus spans more than just DITA requirements and restrictions. The move to DITA and topic architecture has made us question our content: Is the content pertinent to the topic? Or was it just put there to make the book flow? Do users really need it? If they don’t need it, then why are we writing it, translating it, and maintaining it?

With topics, we need topic introductions, not transitions. In the days before DITA, we rarely thought of section introductions as standard. But we’ve discovered that an effective short description can focus a topic more clearly than a title alone can. The short description should state the main point of the topic and provide useful information. For example, suppose you create a topic with a title “Links in DITA.” Instead of starting with a short description that says “This topic is about linking in DITA,” you can start with a short description that says “DITA supports inline links, related links, and map-generated links.” In this way, you are stating the main point of the topic and providing useful information that is not already found in the title of the topic.

Short descriptions are also key retrievability aids because they can appear in search results, as hover text for links, or underneath child links. Writing one or two sentences that serve all these purposes well is difficult, and so editors must provide guidelines and examples to help our writers create effective short descriptions.

Best practices for editing DITA topics

As editors, we must work with writers, with information architects, and with user experience professionals to focus on topic-based authoring from the top down and the bottom up. We must understand and work with the technology while still delivering a complete information experience based on solid information architecture principles. Here are some best practices for editing DITA topics that we collected:

  • Create self-contained topics that are easily moved from one area of the information set to another and that don’t rely on other topics to make sense (after all, topics can be linked to other topics to provide that additional information).
  • Edit the overall navigation structures for the topic collections to ensure that the topic collections are grouped in a way that makes sense for your users.
  • Learn enough about DITA to ensure that the content is represented semantically by the correct XML elements, thereby making you, your writers, and your information more effective and efficient. Also, ensure that the DITA element generates the appropriate highlighting that your style guidelines suggest.
  • Compare the rules of DITA with the rules of your style guides and know where to draw the line for both rule sets.
  • Focus on the content—the content that makes the most impact and the most sense to your users.

DITA offers new opportunities for editors to improve the user experience with information. Editors are becoming leaders in driving the movement to topic-based authoring. After all, books are out; topics are in!

** IBM is a trademark of International Business Machines Corporation in the United States, other countries, or both.

Editor’s Note: This article originally appeared in the December 2007 issue of Best Practices: A Publication of The Center for Information-Development Management (Volumn 9, Issue 6, p. 129, 133-135). You can subscribe to the hardcopy newsletter or sign up for a free e-newsletter at the Center for Information-Development Management Web site:
http://www.infomanagementcenter.com/publications.htm(external link).
Posted on

Keeping up with the Joneses (or Is It Joneses’s?)

Justin Baker

It’s important to keep up with your fellow technical communicators; one should be up-to-date on all of the latest advances in the technical-communication profession. But sometimes we can get too caught up in the latest professional advancements—XML, DITA, information architecture, online help systems, metatags, user-interface eye tracking, etc.

Among all of these sophisticated, bewildering advancements, verbal text (words and paragraphs) is still one of the basic building blocks of technical communication, and good grammar is what makes verbal text solid and valuable. As a result, a good grammar refresher is needed from time to time.

There are many educational tools that can provide such a refresher. One tool that I have found particularly helpful is the Bedford/St. Martin’s Exercise Central 2.0 Web site (http://bcs.bedfordstmartins.com/exercisecentral/(external link)). As you may know, Bedford St. Martin’s publishes the informative Handbook of Technical Writing. When you access the Exercise Central 2.0 home page, you will notice that you have to log on to the Web site. To do so, you need to sign up as a either a student or an instructor—don’t let this deter you. Sign up as a student. If you don’t log in, only limited content will be available to you. (Note: I contacted the Web site’s staff to determine if use of their Web site by common users is a violation of their policy; a staff member stated that it is not against their policy for the Web site to be used by someone who is neither a student nor an instructor.)

Once you are logged in to Exercise Central 2.0, it will be important to note the Tutorials and Exercises hyperlinks under the Web site’s banner at the top. These sections will provide you the educational meat you’re looking for. (The Diagnostic and Scorecard sections are primarily for students and instructors who need to view reports of exercise scores.) The Tutorials section gives you a great refresher on common grammar rules (in addition to usage and style issues), so take that first if you are particularly rusty on grammar. After you have taken the tutorials, the Exercise section allows you to test your grammar knowledge. The exercises are usually 10 questions each with easy option clicks to speed each exercise along. Simply click Submit once you are done with the questions, and you immediately get your score. Exercise Central 2.0 is a very lean, easy method for exercising your grammar knowledge.

Another tool that I have found particularly helpful is Diana Hacker’s Grammar Exercises Web site (http://bcs.bedfordstmartins.com/rewriting/ge3.html(external link)), which is related to Hacker’s book A Writer’s Reference published by Bedford/St. Martin’s. Again, these exercises serve as a refresher on more than just grammar (if you consider grammar in its strictest definition: how words and phrases function in relation to one another to form a coherent language); exercises on usage and style (word choice and sentence style) are also present. Unlike Exercise Central 2.0, these grammar exercises do not require registration. You are prompted to provide a name each time to sign on, but, technically, you don’t even have to do that. Once you have selected an exercise from the exercise menu, either type a name (any name), and click Begin, or don’t provide a name, and click Begin. Diana Hacker’s Grammar Exercises has a slightly more contemporary instructional design with the employment of hyperlinks rather than option buttons, but the overall design is the same—10 questions with easy answering for a streamlined educational experience.

Sometimes our heads can get lost in the proverbial clouds of technical advancements, especially publishing-format advancements. It’s important to periodically ground ourselves and remember some of the basics of our profession. Those basic building blocks include verbal text and grammar. Bedford/St. Martin’s Exercise Central 2.0 and Diana Hacker’s Grammar Exercises can help you get reacquainted with those building blocks.

Posted on

Foreign Words: To Accent or Not to Accent

Lisa Adair

Recent postings to the discussion list brought about a lively debate on the use of foreign words in technical writing. Accented letters occur frequently in foreign words. When writers don’t include the original accent marks, words like résumé become resume, thus creating ambiguity.

One of the posts said that non-native English speakers are pushing for the retention of accent marks. However, it does pose the question of where does it end? Should Greek words appear in the Greek alphabet? Should Russian names appear in the original Cyrillic script? What about “sounds” that are indicated with accent marks?

Plural grammatical features from other languages also become an issue. Is it forums or fora, antennae or antennæ, indexes or indices, appendixes or appendices? Most postings agree that context plays a large role in which spelling you choose. And words like wunderkind would never be pluralized as wunderkinds, but would be wunderkinder per native German.

Editing guides typically don’t get involved in these types of questions. Microsoft Manual of Style advises against using foreign words and phrases since they’re typically not understood worldwide. If your audience is not as diverse, foreign words and phrases might be perfectly acceptable.

Good dictionaries (American Heritage, Fourth Edition) list foreign words. Some German words like bildungsroman, zeitgeist, schadenfreude are listed as acceptable whether or not they’re capitalized. They also track the evolution of words quite well, even if they trail actual usage. For example, Rôle became role as it passed into the English language.

Generally speaking, everyone agrees that using original alphabets in scholarly works is acceptable, but will be viewed as annoying in technical writing. However, proper nouns should be written in the original alphabet as much as possible to respect the capitalization and markings of people who use them, that is, André Breton as opposed to Andre Breton.

Posted on

Book Review of “Effective Onscreen Editing” by Geoff Hart

Virginia Janzig

Geoff Hart’s book, Effective Onscreen Editing (Diaskeuasis Publishing, © 2007), is a readable and useful addition to the general literature on how to be a good editor.

Editor’s Note: To learn more about the book: http://www.geoff-hart.com/home/onscreen-book.htm(external link). To purchase a copy of the book: http://www.geoff-hart.com/download/buy-eoe-book.htm(external link). Geoff is currently revising the book to incorporate review comments that he’s received, fix some infelicitous wording, and incorporate some new stuff he’s discovered since the book was released. Details of these changes and corrections at: http://www.geoff-hart.com/resources/eoe-may2007-errata.htm(external link). The new version should be available online by 11 January 2008 if all goes well. At that time, all purchasers of the previous version will be contacted and offered a free upgrade to the new version.

His main points are that onscreen editing can be fast and effective and can reduce errors when edits are incorporated.

Three of the main topics of the book are what onscreen editing is, what its advantages are, and how to implement it for yourself and introduce it to your team. The focus of the book is how to edit onscreen using Word for either the PC or the Mac.

The book describes using the software tools, editing nonstandard files, editing with software other than Word, finding and using research sources, and safeguarding your work and health. Other topics include information on working with clients and additional detail about Word software.

The book has two primary audiences:

  • Those who have never edited onscreen and need to know how and where to begin, how to be effective, and how to use the tools
  • Those who are currently editing onscreen but want hints and tips on how to be more effective, both with tools and with clients

Most of the information on tools, basic editing techniques, Internet resources, security information, and health concerns is available but can only be found in separate sources. Geoff Hart’s contribution is to bring these topics together in one manageable book and to explain them from an editor’s point of view. He has done an excellent job of describing not only how to be an effective onscreen editor, but also why this methodology is advantageous to our profession. Those managers and editors who are new to this kind of editing can use this book as a set of guidelines to help them understand why and how to implement this technique. Those who already are familiar with onscreen editing can browse to find specific information on new tools, new ways to use familiar tools, how to work with nonstandard files, and much more.

The book has a strong emphasis from the point of view of an independent editor and provides a great deal of information on working with clients. Many of the issues are not relevant to editors in a corporate environment but can be easily passed over.

The chapters on tools, resources, and security provide clear procedures and workarounds. Geoff Hart covers all the tools in Word and how to use them effectively and efficiently. I knew many of them but was surprised and delighted to find some new ones. I also found several ways to improve my use of some of my current tools, such as search techniques, creating effective comments, and using style sheets and exclusion dictionaries. In most cases, I had to test several of the recommendations, which slowed down my reading, but proved that the time and effort were well worth it. For example, on page 215:

“Word offers a nifty shortcut that can quickly reveal whether a global search and replace operation would be safe. Type the search term in the “Find what” field. Then select the option “Highlight all items found in”, immediately below this field, and use the dropdown menu to specify where Word should search for that term (e.g., the main document, headers and footers, comments). Clicking the “Find All” button will highlight all matches in the text in a single step.”

The differences between the PC and the Mac are clear and helpful and are not disruptive. He also covered other software, which makes the book more valuable, especially if you are working with clients who have older or less conventional systems.

Overall, he had good discussions of various editing techniques and especially of Internet resources: how to find them, how to use them, and how to establish the credibility of the source. For example, on page 410:

“As a general rule, give precedence to sites with clear and rigorous editorial policies for controlling the quality of their data.”

In particular, I was pleased to find excellent suggestions for editing less common files, including databases and spreadsheets, as well as Web pages, ASCII, and RTF files. The information also covers editing different tagging languages such as SGML and SML. For example, on page 336:

“The key to opening our horizons wide is the following: most applications, in addition to saving files in their own proprietary format, can also save their files in a range of other formats.”

One of the most important chapters was on the need to save and back up work regularly, as well as make external copies. This chapter also included valuable information on confidentiality, for the client as well as for you.

I do have a few minor criticisms. Three chapters seemed out of place. Chapter 3 is about client relationships, not directly with onscreen editing. It’s important, but I would have made it an appendix. Chapter 13 is about Internet resources. Again, this material is important, but it is not directly part of the onscreen editing process. I would have put it either after the safeguard information or in the appendix portion. Chapter 15 concerns information on backups, upgrades, confidentiality. This information is important information, but it is placed between two chapters directly addressing onscreen editing. I would have made this the last chapter before the two chapters on how to get started with onscreen editing.

I struggled a little with the overuse of long sentences with semicolons. The sentences were all grammatically correct (although I object to the use of “then” as a conjunction). But I found that the long sentences were harder to read, and I frequently had to go back to reread the second clause to make sure that I understood the point.

But these criticisms do not take away from the value of the book. None of the information is extraneous. It is written to editors (and managers) by an experienced editor who has clearly drawn together all the pieces of the work environment that we face daily. He has explained how to make our work easier and more valuable, and has given us a lifeline in a field in which we all sometimes feel we are flailing alone and in the dark. Thank you, Geoff.