TUTORIAL

SUMMARY 䉬

Describes how single sourcing adds layers of complexity, problem solving, and project management to the writer’s task 䉬 Cautions that single sourcing is often a response to a documentation requirement for the market, not to the writer’s need for less complex tools

Single Source in Practice:

IBM’s SGML Toolset and the Writer as Technologist, Problem Solver, and Editor ROBERT KRAMER

T

he promise of single sourcing has been the simplification of the technical writer’s work through the streamlining of the technical process and the creation of dynamic, multi-author teams. The advantages described in much of the current research are many. In single-source architectures, the redundancies of creating a unique document for different formats such as PDF, HTML, or hardcopy disappear, and writing becomes “device independent” (Sapienza 2002, p. 155); that is, it is not linked to a specific tool to create a specific format. One tool now creates all. “A document is updated one time and then ‘transformed’ rapidly and dynamically into multiple formats as needed” (p. 157). Rockley (2001) indicates that writers will become “more proficient communicators and rely less on the tools that are used to display the final information” as singlesource technology separates the creation of content from its output or final format. Single sourcing, she says, will allow skills separation. There will be writers and information technologists with tasks defined along interpersonal skills, preferences, and knowledge (p. 192). Sapienza (2002) writes that technical communicators working with single-source tools such as XML (Extensible Markup Language) are poised to “integrate rhetorical craft with technical wizardry,” perhaps eliminating the imbalance of technical know-how over usability, purpose, audience, and design. William Hart-Davidson (2001) echoes this idea when he describes the status of the technical writer being elevated by single-source technology as “content delivered on the Web becomes the product, and pages 328

TechnicalCOMMUNICATION • Volume 50, Number 3, August 2003

of information comprise the interface” (p. 145). In light of the improvements and efficiencies promised by single-source technology, I want to step aside from the discussions of systems architecture and single sourcing’s implications for pedagogy, and focus on what happens to the writer when plunked down in the middle of a complex, tool-rich, single-source environment. This is a cautionary tale: technology skills and instructional theory are important and have serious impact on how well writers can adapt to single-source writing. Without knowing what can actually happen to the writer, or being aware of the breadth and depth of the skill sets writers must adapt to or abandon in a single-source environment, we grant writing technologies like XML and SGML a certain presumption of elegance. Single-source production can be complex, messy, frustrating, and time consuming. It can task the writer with the development of skills that are traditionally at the core of computer science pedagogy and can jettison traditional technique that is the heart and soul of most technical writing theory. While it can be a writer’s nemesis, it can and does streamline some processes and produce an astonishing range of document types from single-source files, documents that could not be produced any other way within the modern development cycles many companies work in. In the example I present here, single sourcing adds a new

Manuscript received 6 January 2003; revised 4 March 2003; accepted 9 March 2003.

TUTORIAL Single Source in Practice

Kramer

layer of complexity to the writer’s job, expanding authoring duties to include a range of technical and data management skills not typically found on most technical communication course syllabi. The core of these expanded duties is formed by complex problem solving, product knowledge, and software skills. Writers in effect become managers of the tools they use to create, publish, and manage content, and of multiple source and shared files. Unless documenting new products or software, it is common for very little original writing to occur. To adapt, a writer must force a realignment of technical writing skills to a more management-technologist role. In this role, the toolset controls the shape and design of the published documents, so again a shift must take place from what writers know about document design and text structure to accepting what the tools at hand produce within already defined styles. Such an adaptation is neither streamlined nor easy to achieve. What creates the biggest challenge is the lack of separation between writing and the roles of editor, content developer, and technical expert. This situation in turn complicates single sourcing by redefining the writer’s function from specialist in a format or style, to both generalist (in terms of breadth of knowledge across the toolset and documentation) and specialist in product knowledge. An expert, for example, in writing effective instruction sets would find that skill of secondary importance to managing files, controlling output, solving problems, and collaborating with multiple authors across a network. The instruction sets he or she is responsible for may never even be changed or edited in a particular documentation cycle. In the same vein, if he or she has extensive knowledge of which server platforms may or may not require new information about tape drives in their configuration tables, she may find herself acting as a research focal point or team leader for a particular product cycle, but not as a writer.

IBM’s SGML TOOLSET IBM’s Information Development Workbench (IDWB) is a Standardized General Markup Language (SGML) authoring and editing application for technical writers producing IBM documentation. The application produces documents for translation, publishing, and shipment to customers worldwide and produces output in HTML, XHTML, PostScript, PDF, Windows Help, BookManager, and PocketPC Help, all from the same source document. SGML is a meta-language for text markup. Authors write text and insert textual tags that define content types within a document, such as “title,” “footnote,” and “list entry,” rather than information that defines appearance such as “bold” and “italics.” IBM describes this as “what it is” markup instead of “how it looks.” Documents created in

SGML can be used as single sources for other markup languages such as HTML or IPF. By adding rules and styles that define the “what it is” structures, or the presentation aspects of content used in a file, the same files could be formatted into PostScript or other presentation-specific formats. It is worth making a note about SGML and XML: Most discussions of single-source technology advance XML as the preferred and best authoring language to date. SGML was developed in the early 1980s; XML, often referred to as a child of SGML, was developed and endorsed by the World Wide Web Consortium in 1998 and promised a superior single-source language, particularly for authoring for the Web. The tool I describe in this article, IDWB, is wedded to IBM’s extremely complex, global documentation needs. It supports IBMIDDoc, an SGML application that supports authors in creating IBM documentation, and it is the only tool that will author an English document and render that same document in PostScript in 43 languages and in XHTML in 45 languages.

SIMPLIFICATION? In his discussion of XML and the changing role of the technical writer, Battalio (2002) notes that the sweeping changes predicted (Grice and Krull 2001) in the documentation process and the job description of technical writers may be coming to fruition (Battalio, p. 211). These changes have been described as the simplification of the technical writer’s job and the move from being “mere writers of documents to architects of information structures” (Battalio, p. 212). Single sourcing automates many of the critical rhetorical features that comprise the authoring job: page layout, typesetting, and text design. IDWB relies on document type definitions (DTDs) for formatting and style definitions across the range of document types. Without publishing a document to PDF or HTML, the writer does not see the text in its published form and has no direct control over its structures. This removal of design and format control is often considered a simplification of the process. The writer, in effect, no longer has to worry about making such decisions, or controlling intra- and supra-textual features, and thus, authoring is easier. Without question, it is easier to produce multiple documents for multiple media types; yet single sourcing can also increase complexity in other ways that writers aren’t traditionally prepared for. In the small information development group I’ve used as a benchmark here, new writers with technical communication backgrounds authoring work with a DTD learned to surrender visual control of their documents, to ignore widowed lines of text, split tables, or orphaned headings. Their training had conditioned them to control those elements for correctness; Volume 50, Number 3, August 2003 • TechnicalCOMMUNICATION

329

TUTORIAL Single Source in Practice

Kramer

Figure 1. Embedded files, to a master file, to an IDWB client, and finally back to the version control library.

relinquishing that control was a challenge. With embedded conditional statements in each SGML document, an author might fix an orphaned heading in a shared document being edited for a UNIX© book, only to find it orphaned again in the AIX© or Windows© version either because UNIX-specific information was not printed, or because AIX-specific information was added: either case would cause an uncontrollable text shift.

THE PROCESS Within IBM’s information development process, there is no distinction between “writers,” or content developers, and what Rockley refers to as “information technologists,” or those responsible for all aspects of output (p. 192). Writers manage both content and output of shared files across a wide range of publication types that pull from a core content or single source. The complexity of this process is the result of several characteristics of IBM’s SGML toolset, IDWB and the Arbortext Epic Editor. 䉬 Source files exist on remote servers and networks; many of the files that define structure are invisible. 䉬 The Epic Editor has an intense learning curve and uses metadata conditional statements extensively to control version, platform, revision, cross-referencing, and indexing information. 䉬 Databases that contain source files require management by team leads as well as by individual writers using a feature-rich version control system. 330

TechnicalCOMMUNICATION • Volume 50, Number 3, August 2003

䉬

Without publishing to PDF, writers are unable to display hardcopy content on screen as it will appear in publication, nor easily preview select sections of a document. 䉬 The output or compilation of publication files is time intensive and complex, requiring multiple support files that control SGML settings, symbol entities, publication standards, and platform information. Small mistakes cause significant problems and time delays. 䉬 A high degree of product knowledge is required to understand the relationship between files and the structure of master source files that control the content of every publication. Without expert product knowledge, it is impossible to acquire a clear visual mapping of the information landscape and the likely location of information. Figure 1 displays the basic process of working with a file in IDWB. In Figure 1, a source file is checked out from a remote document library in CMVC, a version management tool that controls and houses all files for publication. The file is opened on a local client and edited in IDWB using the Epic Editor. A master file may contain hundreds of embedded files, and those files may contain dozens of additional embedded files, cross-references, and markups for symbol or text entity files. Figure 2 displays this expanding file set. Each embedded file also contains cross-references to other files and structures in the document library; to draw

TUTORIAL Single Source in Practice

Kramer

Figure 2. Embedded and invisible files, from version control library to individual files.

them all here would make this diagram incomprehensible. Suffice it to say that there are hundreds of cross-references to structures within single documents, to structures in external documents across libraries, to files in use and not in use, and to other master files. The editor in ID Workbench provides tools for checking on the integrity of SGML, but large documents require a mastery of how information in one file may affect information in another, and how to decode errors and resolve conflicts affecting an entire range of files that define a particular document. Putting the processes described together so far would result in a diagram that looks like Figure 3. I’m being a bit tedious in illustrating this process for a reason; it is complex and difficult to visualize even when using the tools, and I’ve only shown the basic structures of the process here. What quickly becomes obvious is that the markup language becomes secondary to this process. What drives the complexity for the writer in this model is the architecture required to support dozens of writing teams across remote sites, translation into dozens of languages, the support of up to seven machine platforms, and the requirement to produce HTML, PDF, Winhelp, and additional specialized media types all from single master files. With that said, I can safely venture that single sourcing is only as streamlined and simplifying as the documentation goals and requirements of the business adapting it. Neither can be considered separately. For large companies with global document goals, it may be that single sourcing will streamline the creation of multiple formats by introducing DTDs and strict controls over format, but only at the cost of increased job complexity for the writer, who now becomes a file-management technologist and trouble-

shooter extraordinaire. Can the complexity increase? Yes. Conditional text forces writers to visualize structures. Examine the SGML markup in Figure 4. This statement is saying that the phrase (⬍ph⬎ ⬍/ph⬎) “Drive X12 is not supported.” applies only to the platforms AIX, HP, Linux, or Windows. If the file this phrase resides in is ‘run’ for any other platform than those, the phrase will not print. This is a simple conditional markup and is common. Conditional expressions can also be one of the single most complex features a writer will work with; some text structures contain multiple conditional markups, chopping sentences into short phrases or word blocks that create single paragraphs of information that are applicable to several different platforms. Conditional expressions represent the skill that Rockley refers to when she writes “Technical writers need to understand how information can be used in multiple ways as they write to ensure their content is reusable” (p. 191). The complexity this adds to the writer’s task comes in the form of troubleshooting why certain conditional statements fail, how to organize extensive texts that must be valid for multiple, unique versions; how to control versions of texts where a new feature may only be true for the current version of a product, but only on a few platforms. The scenarios are endless. Writers working with conditional statements are forced to visualize how a specific structure will appear in the final document depending on what platform (AIX, Windows, Unix) it is published for. Take the example a bit further and see how easily complexity—and room for error—increases in Figure 5. Volume 50, Number 3, August 2003 • TechnicalCOMMUNICATION

331

TUTORIAL Single Source in Practice

Kramer

Figure 3. From version control library to IDWB client to master files to embedded files.

Figure 4. An example of conditional text.

Figure 5. More elaborate conditional statements. This figure is an example only. X12 is not an actual drive, nor are the 8234 mirage and 82LPS-divit actual SCSI adapters. Some props values have been changed for clarity.

THE WRITER AS TECHNOLOGIST Without straying too far into the technical intricacies of IDWB, which is not my purpose here, I have tried to describe a single-source process that is defined by the 332

TechnicalCOMMUNICATION • Volume 50, Number 3, August 2003

requirements of the documentation, the end-user, and ultimately IBM’s global documentation goals. It is both streamlined and layered with complexity. This process both from the technical demands it makes, and from the file

TUTORIAL Kramer

management expertise that must be developed to be an effective team member, defines the writer’s duties. A typical set of responsibilities for a writer during a development cycle could include: 䉬 Manage all owned files and keep current updates of shared files available for other writers. Check in files weekly to maintain current file base. 䉬 Book owners ensure that books “run” error-free; report file errors to the owners of the file. Run both PDF and HTML versions of all books owned. 䉬 Verify new content with development and team leads before formal reviews. 䉬 Check revision marks for current production cycle on all new or updated content. 䉬 Verify props (conditional statements) information for each platform that affects document. 䉬 Update indexing. 䉬 Update branding information. 䉬 Prepare book for review in HTML and PDF formats. 䉬 Update new cross-references or related files, if any. This list is heavy on the technologist side. Rockley is correct in saying that “rather than narrowing the scope of what writers do, single sourcing actually increases the scope” (p. 192). She is referring to the increased awareness writers must have for how information will fit for a range of audiences and formats, and the proficiencies writers will develop to write for those audiences and formats. But as the list above indicates, there is also an increase in the scope of technology expertise and project management necessary to do the job and in the example I’ve presented here, not an increase in audience awareness and writing for multiple genres. Rockley writes: Overall, writers gain by creating single-source materials. No longer do they have to contend with the “boring” job of updating materials. Now updates are always related to new content, and information that stays the same is untouched. Changes to existing material are fast; a change to a single element automatically updates it wherever it is used. Time that was previously wasted doing mechanical or “busy” work can now be spent on creating new material and creating innovative changes in information delivery (p. 192).

Her vision is true for many cases, but not universally. One of my goals here is to make sure we realize that single sourcing is often the result of an industry requirement to meet a documentation goal rather than an evolution of the writer’s craft toward ease and simplification. As with IBM’s IDWB, an SGML toolset is the only way to continually achieve the global translation and multiple format publication of IBM documentation that is unique to the company. The technology is a response to a market and technical

Single Source in Practice

requirement that the writer in IBM Information Development must adapt to and master. It is not a response to writers’ desire to streamline their workflow and that is not what it accomplishes. In the process I’ve described here, updates are not always related to new content, but to changes in existing content. Changes to embedded symbols or text entities such as URLs or product names can be made easily but often have to be checked manually for clarity or ‘hard coded’ to maintain a sentence structure. There is extensive “mechanical” or busy work in the management of files, conditional expressions, error tracking, and version control. With a legacy product, not unusual in software writing, there can be little creation of new material and within the rigorous standards demanded by toolsets like IDWB, little room for innovative changes in delivery. Rockley’s description of fast updates and the elimination of busy work are not givens: this is the presumption of elegance I cautioned against at the beginning of the article. Single sourcing must be evaluated in the context of a documentation requirement, its scope and complexity. As in my IBM example here, solving the challenges of formatting for multiple platforms, creating multiple document types and enabling version control across writing teams does not by default make the writer’s job easier or content more innovative. It solves specific market issues that are external to the writer’s job, whereas the internal technical challenges to meet that requirement often increase.

COPING WITH THE CHALLENGES How do writers in IBM Information Development cope with the increased challenges in their job? In several cases, IBM Information Development teams have evolved as groups through various toolsets in the last decade, arriving at IDWB with a strong product knowledge and a facility with databases, shared files, and a knowledge of what the components are that produce IBM documents. New members to these teams enjoy a collaborative learning effort with the acknowledgement that it takes time to tackle the learning curve. Those who adapt quickly to the toolset and to the requirements of single sourcing typically share the following traits: 䉬 Expert product knowledge—the ability to research and interpret technical descriptions of product features quickly and accurately 䉬 Strong multitasking ability—working with multiple tools and virtual libraries while also organizing teams, schedules, and managing unscheduled changes to documentation 䉬 Strong interpersonal skills and team awareness 䉬 Strong problem-solving skills that are grounded in an understanding of the toolset: Running a book hours before a deadline and finding a critical error Volume 50, Number 3, August 2003 • TechnicalCOMMUNICATION

333

TUTORIAL Single Source in Practice

Kramer

sourcing are many and good. The automation of the tedious tasks required to create multiple versions of information is reason alone to adopt languages like XML and its applications. But it is important to note that single sourcing is often a response to a documentation requirement for the market, as with IBM’s IDWB, and not a response to the technical writer’s need for less complex tools. Assessing that documentation requirement, and developing an awareness of what skill sets may change, and what new skills may be required of writers, can make a transition to single sourcing rewarding rather than surprising. TC

Figure 6. Technical variables introduced by single sourcing.

requires a quick and practiced response Understanding document types, such as HTML and PDF, and the ways they are generated 䉬 Willingness to relinquish design control to a DTD and focus on content and file management as explicit job duties. 䉬 Strong ability to work and learn independently. Technical communication pedagogies stress collaboration across writing teams, but often, information is collected, edited, and verified individually before being shared with the team 䉬 Strong ability to work in a nonlinear mode (Software writing in particular often moves from A to D to C to B rather than A-B-C-D. The most effective writers are those that accept change as the one constant and can visualize where and when bits of information exist in a networked system of shared files,) There are other skills specific to certain job functions; managing Webhelp files, for example, but this core set seems to be the absolute requirement for successfully managing the document process in IBM Information Development. By defining the set here, I hope to show that not all the skills are related to writing or editing and many of them are direct results of the single-source architecture itself. Coping, and growing, with the toolset is the result of immersion, collaboration and team support, and natural facilities with complex tools and visualization. 䉬

THE SOMETIMES REALITY OF SINGLE SOURCING New technical variables introduced by single sourcing are significant, as Figure 6 illustrates. The merits of single

334

TechnicalCOMMUNICATION • Volume 50, Number 3, August 2003

REFERENCES Battalio, John. 2002. “Extensible Markup Language: How might it alter the software documentation process and the role of the technical communicator?” Journal of technical writing and communication 32:209 –244. Grice, Roger, and Robert Krull. 2001. “2001, A professional odyssey: An introduction to this special issue.” Technical communication 48, no. 2:135–138. Hart-Davidson, William. 2001. “The core competencies of technical communication.” Technical communication 48, no. 2:145–155. Rockley, Ann. 2001. “The impact of single sourcing and technology.” Technical communication 48, no. 2:189 –192. Sapienza, Filipp. 2002. “Does being technical matter? XML, single source, and technical communication.” Journal of technical writing and communication 32:155–170. ROBERT KRAMER studies visual rhetoric, information design, photography, and professional communication. He has published research on Web-based writing, document design, and collaborative workplace theory, and he has made presentations on digital video production, multimedia, visual thinking, and teaching technical writing. His awards include the Ken Caird Award for Best Graduate Student Publication in Technical communication’s November 1996 special issue. After completing his doctorate from New Mexico State University in 2000, he produced interactive media and Internet Webs for a Federal Challenge Grant, and most recently he worked for IBM Information Development. His focus is increasingly on visual thinking and how it impacts writing in distributed, multi-author, shared file systems. Contact information: [email protected]