Newsletter of the Society for Technical Communication, San Francisco Chapter
December 2004/January 2005
|
Newsletter of the Society for Technical Communication, San Francisco Chapter December 2004/January 2005 |
David Knopf, President and founder of Knopf Online, introduced several complex topics at our September 15th chapter meeting, and he did it in a way that helped all the pieces fall into place. Comments from members ranged from: "Now I understand where I fit in the single source process," to "I liked learning how FrameMaker's variables and conditional text relate to entities and attributes in XML." David Knopf successfully took us from a 30,000-foot overview to the 3-foot details in under two hours.
Knopf provided evidence of two trends in technical writing: Document-based single sourcing is now robust and stable, even in small- and medium-sized publications groups; and the XML revolution has begun in earnest for medium- and large-sized publications groups.
"Single sourcing is not the thing to start on Tuesday and have it up and running on Friday," says Knopf. "Just say no to quick and dirty solutions such as repurposing content and tweaking the output." To succeed and save money, single sourcing requires a disciplined, template-driven approach to content authoring. What is single sourcing? It is a way of organizing information in documents or in information objects so that different outputs can be generated automatically from the same information without having to tweak it. Outputs may include different formats, such as print, PDF, Help, or web pages. Or outputs may target different audiences, such as programmers, end users, or system administrators. Finally, single sourcing may be used for different versions of products, such as Lite versus Pro. "It's a myth to say that writing is different for print versus online help," says Knopf. "It's also a myth to say that single sourcing is too expensive."
Implementing document-based single sourcing is reasonably inexpensive and relatively easy. Authors write in standard editing tools such as Word or FrameMaker and use conversion tools to generate online output. Conversion tools include Mif2Go, WebWorks® Publisher, and Doc-to-Help®. For approximate numbers for costs and schedules, Knopf estimated the an expense of $5,000 to $50,000 and two to six months time to implement a document-based single source solution.
In contrast, database-driven single sourcing involves significant implement costs and is time-consuming to implement. It requires a rigid, structured approach to authoring and special skills and tools. But, information objects stored in a database provide virtually unlimited flexibility for producing different outputs. "Don't write documents anymore," says Knopf. "Write information objects." AuthorIT and Veredus by Rascal Software are two tools used for database-driven single sourcing.
Single sourcing is now firmly established as a recommended method for writing and publishing small, medium, and large publication projects. One-time setup costs plus recurring costs result in significant savings by the second and third revision cycles of projects written in one language. And for projects involving more than one language, cost savings are immediate, affecting the first cycle's bottom line.
Single sourcing means writing once, reviewing once, then re-using information objects in multiple output formats. Single sourcing requires templates, strict adherence to style guides, and up-front planning that pays off in the end.
Structured authoring can be done without XML, but XML cannot be done without structured authoring. Structured authoring is a concept, whereas XML is a technology that enables structured authoring.
Structured authoring is a method of writing and arranging content that relies on rules and automatic validation to enforce the rules. Structured authoring separates content from presentation; information is labeled according to its purpose. For example, a word and its definition may be labeled a glossary term and a glossary definition in structured authoring.
This type of writing may restrict or constrain you at first, but it saves time in the end by forcing documentation to be complete, consistent, and designed for re-purposing. Editors no longer have to worry about missing parts and can spend more time on awkwardly written sentences or misinformation. Writers spend time on content and are no longer permitted to apply formatting.
Benefits of structured authoring include improved document quality, improved author productivity, and enhanced content sharing and re-use.
XML is a platform-neutral, vendor-neutral, open standard metalanguage that stores structured content in text files. XML separates content from format. Formatting is determined by an information architect or template designer, and authors cannot override the automatically applied formatting. There are no exceptions. In XML, information is divided and subdivided into logical parts that follow structure and hierarchy. XML makes us think about and identify the rules of structure and hierarchy ahead of time, then adhere to the rules for a big payoff in the end. XML documents are written to follow rules, and you can't break the rules if you are an author or editor.
Knopf showed us an example of an unstructured document, a formatted recipe, versus a structured document, a recipe written in XML. In the XML recipe, types of information such as the number of people served and individual ingredients were tagged according to content. Knopf used the recipe example to explain technical details related to XML such as definition documents, elements, attributes, entities, and syntax.
XML software for authors includes the expensive Epic Editor as well as the less expensive FrameMaker 7.x, XMetaL Author, xmlspy Enterprise / Pro, XMLmind, and Serna. For information architects who develop definition documents such as DTDs (Document Type Definitions), tools include FrameMaker 7.x, XMetaL Developer, xmlspy Pro / Home, and Epic.
In structured authoring, there is more planning up front, but you save money right away when you start on your revision cycles. Structured authoring and XML are not right for every organization or project, particularly not lone writers. They cannot be implemented in a week or even a month, but despite their complexity they are doable. For medium- and large-sized publication groups, they provide significant measure benefits such as improved content quality, improved author productivity, content re-use, and cost savings. You can set up the system using an information architect, a template designer, and authors, and information architect and the template designer can be the same person. After the initial system is defined, authors and editors take it from there until a major change in content or formatting is required.
My take-home message as an author was:
I can write and review my information once, then request print, online help, and web output without tweaking, formatting, or exceptions.
My take-home message as an information architect or template designer was:
I can help companies organize their information, then separate content from format for maximum flexibility.
Alison S. Gemmell is a senior technical writer with a chemical engineering degree. As an engineer, Alison writes technical reports for site cleanups, permit applications for air, water, and hazardous waste treatment, and pollution prevention plans for manufacturing processes. As a technical communicator, Alison took courses in XML and XSL and would like to work on an XML structured authoring project someday.
Copyright © 2004 by the Society for Technical Communication, San Francisco Chapter (www.stc-sf.org). This article may be reprinted in another STC publication under the provisions of the chapter's copyright policy.