Monthly Archives: March 2008

Who Are We? What Should STC Be?

Mike Hughes

I am Mike Hughes, and I am running for Second VP for the Society for Technical Communication. In this article I tell you a little about me and my vision for our profession.

Who am I?

I am a Society Fellow currently on the editorial advisory board for Technical Communication and the Ken Rainey Excellence in Research award committee. I chaired the subcommittee on Research at the STC Academic-Industry Leaders Summit in 2007, and I was organizer and leader for the Sharing Corporate Knowledge Institute at the Summit Conference in 2007. I am also currently filling an interim director position on the board. In my day job, I am a user assistance architect for IBM. I have a master’s degree in Technical Communication and a PhD in Instructional Technology, and I am a Certified Performance Technologist through the International Society for Performance Improvement.

Who are we?

Technical communication is a diversified profession, one that supports multiple career paths and roles. Whether we call ourselves technical writers, information developers, instructional designers, content managers, or whatever, we improve the user technology experience by providing information that eases and enhances that experience.

When our profession was initially emerging, we stated our value in terms of the correctness and completeness of our documents and the clarity of the language in those documents. Then, as we matured, we started defining our value in terms of how we benefited our end users. And now we are taking our value proposition to yet a higher level: how we support the missions and objectives of the organizations that employ us. This means that our value can’t stop at the quality of the communications we produce; it must extend to the effectiveness of the actions they enable, and beyond that, to how the improved effectiveness of our users benefits our sponsors. The list is long, but these are just a few:

  • Increased customer adoption (because new products and services are easier to install and use)
  • Reduced support costs (because product owners can maintain their own products better)
  • Lower medical costs (due to better patient compliance with medicines and procedures)
  • Improved product quality and reduced production costs (because workers can comply with best practices that are easily understood)
  • Increased customer loyalty (because the web sites and other communication channels we create build communities of common value and interests)

 

What should STC be?

If those are some of the things we are about, what should the role of STC be?

  • Provide professional development programs in the core body of knowledge that defines us as a profession
  • Show leadership and provide education in the emerging tools and technologies that direct our future as a profession
  • Serve as our advocate within government and industry to articulate our contributions and needs as a profession

We have invested a lot of our society energy and resources over the last several years in improving the structure and governance of STC. I think we can quit reinventing ourselves now and put our new structure to work. We need to shift our focus outward again and ensure that as members we are getting full value for our dues. My main focus as an officer will be the following:

  • Maintain a balanced budget that funds the programs that add the most value for members
  • Ensure that our publications and conferences provide the content that helps members do their jobs
  • Create a collaboration where members, vendors, employers, and academic communities help technical communicators keep up with the ever-changing demands for tools and technology knowledge
  • Support a certification program through STC that helps our sponsors trust and understand our value and that creates sustainable careers for technical communicators.

Please visit my website at http://www.mindspring.com/~mikehughes/index.htm(external link) to get more information on my background or read some of my published papers. Go to my blog at http://user-assistance.blogspot.com(external link) and click the STC label to read more about my positions and thoughts on specific topics related to my candidacy.

The Impact of XML on Technical Editing

Justin Baker

I remember hearing a lot of chatter at the beginning of this decade about something called XML. I remember hearing about the unknown implications for editors: Would the paradigm of structured documentation and single-sourcing models make editors all but obsolete? I saw myself in a museum behind thick glass. Because of this thing called XML, were we all doomed to go the way of the Gutenberg press?

Well, hardly.

I’ve learned a little about XML over the last seven years, and I feel a little more at ease. To understand XML’s impact on technical editing, let’s first look at a brief overview of the major editing phases of linear-based documentation. We will then examine the nature of XML before finally moving on to how XML affects technical editing.

Linear-based documentation (traditionally called paper-based documentation), has three major editing phases in my own mental editing model: (1) Knowledge Editing, (2) Language Editing, and (3) Layout Editing.

  • Knowledge Editing refers to the technical subject matter in a document both in verbal form (words) as well as in visual form (images). I divide Knowledge Editing into four sublevels: Knowledge Accuracy, Knowledge Completeness, Knowledge Logic, and Knowledge Hierarchy. The first two editing sublevels ensure that the subject matter is accurate and complete. The third editing sublevel ensures that the basic logic of the subject matter is sound, and the fourth editing sublevel ensures that the 1.0, 1.1, 1.1.1 hierarchy of the subject matter is sensible.
  • Language Editing refers to the technical subject matter in a document both in verbal form and visual form. Language Editing focuses on the exposition of the knowledge through words and images. Language Editing encompasses sentence structure, grammar, diction, punctuation, spelling, and character mechanics (font and display attributes). Language Editing focuses on the particular standard visual elements to be used in any given type of illustration. For example, for network diagrams, some companies might want to consistently use the same network-server icon. Language Editing ensures that both the verbal language and the visual language are standardized.
  • Layout Editing focuses on the following document areas:
    • Industry-standard, large-scale document page layout patterns (for example, a traditional template for a specific industry project plan)
    • Text and illustration spacing
    • Large-scale font formatting (small-scale, or individual, font formatting is part of character mechanics under Language Editing)
    • Miscellaneous layout mechanisms such as running headers, page numbers, and hyperlinks

Now that I have laid the editing foundation for this examination, let’s examine the nature of XML before we see how it affects the editing model.

XML (eXtensible Markup Language) is a metadata language that allows you to tag a chunk of text with labels that explain the nature of that chunk of text. XML promotes the use of tags that indicate “this is a name” or “this is an inventory part.” XML also controls the structure of a document to a large degree. Using the same set of labels, or XML tags, you can dictate the pattern of particular chunks of text. Perhaps you simply have a set of XML tags that are “heading” and “paragraph.” You can dictate rules for the structure of the document such as a paragraph must always appear right after a heading or a figure can never appear without a caption. The library of XML tags and the organizational rules for their use within a specific document is referred to as a document type definition (DTD) or an XML schema. So, we have tags that describe the nature of chunks of text within a document, and we have restrictions about how the document can be structured.

For the purposes of this article, there is at least one more way that XML can control a document: layout. A complimentary standard of XML called the XML Stylesheet Language (XSL) can dictate how particular XML tags are displayed. While XML focuses on describing the nature of text, XSL dictates whether a chunk of text appears bolded, or centered, or whatever. With XML and XSL, the nature of text and the formatting of text are kept completely separate.

So how does XML affect technical editing? Well, XML doesn’t control every aspect of technical editing to the point that you and I are relegated to the role of spellchecker, but XML does take a significant amount of control away from the technical editor.

How Does XML Affect Knowledge Editing? XML cannot control the accuracy or completeness of text. Unless XML is instilled with artificial intelligence in the future, it never can, and it never will. However, XML does control knowledge logic and hierarchy to a degree. For example, an XML DTD can control whether chunks of text tagged with a paragraph tag can occur after chunks of text tagged with a heading tag. However, XML cannot control the logic and hierarchy within the tagged chunks of text.

The XML DTD may be able to control the structural logic of the text to some rudimentary degree (for example, the pattern of tagged text must be heading-paragraph-heading-paragraph-subparagraph), but it cannot control the substantive logic within a paragraphs or within a sentence. You could have what is called a well-formed XML document, in which the pattern of heading text chunks and paragraph text chunks satisfies the rules of the XML DTD, but those text chunks could contain complete gibberish, and the XML DTD would not know the difference.

How Does XML Affect Language Editing? XML has the least control in this area. You can tag a chunk of text with a paragraph tag, but that tagging cannot control the sentence structure, grammar, diction, punctuation, or spelling. You can still write a horribly structured sentence, and the XML DTD would never know the difference. Bad spelling could also be rampant in an XML document. As part of the style rules in the related XSL, the character mechanics can be controlled: headings can be made to be a particular font size, case, etc.

How Does XML Affect Layout Editing? This is where XML dominates technical editing across the board. Everything within the layout editing can be controlled by the DTD and the DTD-related XSL: industry-standard, large-scale document page layout patterns; specific text and illustration spacing; large-scale font formatting; and miscellaneous layout mechanisms such as running headers, page numbers, and hyperlinks. With a document developed using XML, the technical editor doesn’t need to focus on these layout aspects. XML allows the technical editor to focus on knowledge and language.

As you can see, XML does not relegate technical editors to the trash bin of technical documentation history. Even with the restrictions of XML, technical writers have a lot of room to maneuver, and therefore a lot of room to make mistakes. Where there are mistakes, there are technical editors. Technical editors are still needed to edit for accuracy and completeness, and to a large degree, a human brain is still needed to ensure correct logic and hierarchy. All the traditional language skills are still needed. Layout is governed largely by XML, but, for those of you who always loathed setting margins and making text bold at a 14-point font size, your day of deliverance has come. Until an XML language is developed with an artificial intelligence that can recognize the illogical structure within any given sentence or that two sentences have been turned around, a technical editor will be needed.

STC as the Global Leader for Technical Communicators: Rich Maggiani’s Vision

Rich Maggiani

STC needs Board members who are experienced in the field, who understand our profession and the contribution we make to the world, who recognize the role that STC plays in representing and promoting our profession, who understand the services STC must provide for our membership, and how STC must be the global leader for us. This is my vision for STC and one that I will arduously pursue as your Director-at-Large.

I care deeply about STC. I have been an STC member for more than 12 years. I have held a volunteer position in every one of those years, beginning with being a co-founder of the Vermont chapter to my current role of leader of the Public Relations committee (which has 18 international members). Last month, I was honored to become an STC Fellow in recognition of my work as a marketing and technical communicator.

My profession is technical communication. I have been practicing that profession for well over 20 years. In my work, I constantly focus on promoting technical communication as a profession, and technical communicators as professionals who create unending value.

Experienced with STC Board matters. I have been doing STC Board-related work for over three years now. Three consecutive Board Presidents have appointed me: one year as Assistant to the President for Competitions; two years as Public Relations leader (my current position) where my committee has been breaking new ground in researching and promoting technical communication and technical communicators around the world.

Experienced as a Board Director. I am experienced with Boards of Directors. I have been Board President for the Vermont Businesses for Social Responsibility (VBSR) after sitting on that Board for four years. VBSR is a state-wide business organization. As Board President, I directed a transition from a tactical to a strategic Board. I have also been Board President for two years for a food cooperative in New York after having sat on that Board the two previous years.

Business experience. For over sixteen years, I owned and operated a full-service marketing and technical communication agency. Currently, I am running Solari Communication, a company dedicated to applying technical communication to help clients increase sales and profitability. As a business owner, I understand how STC as an organization must operate to be successful, I understand the inner workings of technical communication and how to successfully market and promote our profession.

Educational experience. I currently teach technical communication to undergraduate students at Champlain College in Vermont. Previously, I taught graduate students at Saint Michael’s College business writing and communication skills. I am certified to teach secondary education through adult learners. I have also presented numerous sessions on communication topics to STC local, regional, and international conferences as well as other organizational conferences.

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).

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).