Developing a Lingua Franca: The Common Glossary

Home/Publications/Best Practices Newsletter/2003 – Best Practices Newsletter/Developing a Lingua Franca: The Common Glossary

CIDM

April 2003


Developing a Lingua Franca: The Common Glossary


CIDMIconNewsletter Beth Fischi, Senior Technical Writer, Motive Communications, Inc.

To communicate effectively, both internally and with customers, most technical publications departments recognize the need for a glossary. For example, the word server , commonly used in software documentation, can refer to hardware or software depending on context. Two years ago, everyone at our company used the term differently, unnecessarily complicating discussions. Our company’s product consisted of multiple servers (hardware) running multiple servers (software). By familiarizing everyone with this term in a single glossary, giving the term one meaning, and providing alternate terms for other meanings, we greatly reduced the confusion, saved time and energy, and decreased the risk of passing along misconceptions to the customer.

Creating the company glossary required a company-wide education process over about six months. Before this effort, departments in our company of about 240 employees lacked a common terminology. We struggled with issues like these:

Writers created glossary terms on-the-fly using different documentation tools, or terms were not provided at all.

Writers would duplicate terms because they didn’t know others had already defined them.

Engineers and writers used different terms to mean the same thing.

Terms were often vague even in context.

Multiple glossaries were published on our intranet. Consequently, no one knew which of several competing definitions was official, and so the glossaries were used inconsistently.

To address these shortcomings, our technical publications team developed a company glossary that would serve as a lingua franca, or common language, and a conceptual foundation for our company and our customer deployments.

Goals and Approach

Our goals in creating the company glossary were

  • to clarify meaning for external readers who encounter many new concepts when learning our product
  • to promote clarity during information development through the use of a common language among software engineers, marketers, technical writers, and other members of our company who often-even within one discipline-use their own terminology or distinct jargon
  • to be able to reuse glossary termsBecause we transform XML source to many formats, we needed to write the source once and use it in many places: PDF guides, mouse-over terms in online help, and links in HTML Help. The definitions that appear in our installation and reference guides must be consistent with those in online help and white papers.
  • to save money on translation costsReusing the same definitions in different types of documents and across versions saves money because glossary definitions are kept in translation memory and can be reused without the cost of retranslation.
  • to establish consistency in the translation processTranslators who fully understand the meaning of a term can better judge how to translate it in context.
  • to reduce unnecessary consensus-gathering and editing efforts by publicizing the company glossary within our marketing organization, thereby helping us reach the objective of a common languageProduct requirement and marketing documents that use terminology from the company glossary require less editing and tell different pieces of the same story.

Our documents are written in XML as an instance of the DocBook DTD1. DocBook is not an application, but rather a DTD, or Document Type Definition, which defines the tagging rules for books and articles. Oasis.org defines it as “an XML/SGML vocabulary particularly well suited to books and papers about computer hardware and software….” We use the DocBook XSL stylesheets2 to generate PDFs, HTML, and HTML Help3.

In May 2001, a section in DocBook: The Definitive Guide (O’Reilly 1999) by Norman Walsh and Leonard Muellner inspired us to automate glossary generation for our documents. Because we wanted a feature-namely, a glossary database-that the generic DocBook XSLs did not provide at that time, we implemented our own solution in XSLT (Extensible Stylesheet Language Transformation). Since then, Walsh has added a similar feature to the freely available DocBook XSL stylesheets4. If you write in DocBook and use Norman’s XSL stylesheets, you can use this feature without major development effort.

Our writers create the company glossary source in a single XML document, which then undergoes several reviews. Thereafter, all writers in the group reuse definitions effortlessly. They do so by choosing a glossary definition from a menu in the Corel XMetaL XML editor, then marking vocabulary in their documents with the appropriate tags. When the writer “spins” the document (transforms it from XML to an end-user format, such as PDF), the selected glossary definitions are included in a glossary section generated automatically at the end of the document or in another appropriate place if the document is not a traditional manual.

Using XML is not essential to implement a glossary as a best practice in your organization. If you do not already use XML, you may want to carefully consider whether it is, in fact, for you. If you decide to create a reusable glossary, you can use the following attributes of our glossary process as a springboard in your planning. Our glossary is

  • written in XML conforming to the DocBook DTD
  • produced automatically during document generation
  • centrally located (the glossary file is located in one place in our version control system)
  • scheduled as part of each official project
  • contributed to and reviewed thoroughly by multiple departments
  • integral to technical publications operations in both processes and tools

Roles

When planning a company glossary, design the creation and maintenance process around the roles in your organization. In our company, we developed a process that involves these roles:

  • Technical writer: Develops the definitions in consultation with software engineers.
  • Software engineer: Reviews definitions for technical accuracy.
  • Marketing representative and project manager: Reviews definitions for adherence to the marketing message.
  • Lead writer: Reviews definitions to ensure a good fit with the model for the whole documentation suite.
  • Peer editor: Reviews definitions for applicability, style, and consistency.
  • Proofreader: Proofreads all definitions after major revisions are implemented. In addition, ensures that the individual glossaries are reviewed in context in each draft of a document.
  • Tools person: Modifies XSLs to address any needed enhancements (such as branding) and maintains customization layers for the DocBook DTD and Walsh’s XSLs. Works with the localization team to answer or address tools-related translation issues. (In our group, the tools person is a technical writer who has cultivated XML and scripting knowledge.)
  • Configuration management engineer: Implemented a custom documentation build system for our specific content reuse needs. Implemented our custom version of the XSL for generating the glossary. Because the glossary-collection feature is now a standard part of the DocBook XSL stylesheets, this role is no longer necessary to implement your own shared glossary with DocBook. However, you should have someone on your team who is good with tools (see the tools person role).
  • Localization team: At major releases, the glossary is sent for translation. A localization person works with the translation team and the tools person to produce the final glossary.

Challenges

If you decide to implement a company-wide glossary, here are some of the principal challenges you may encounter (also see Planning ROI):

  • Adjusting your goals to the size of your company or organization. Our original glossary was implemented for a modestly sized company of approximately 240 employees. Implementing a company-wide glossary for large and geographically diverse companies is more complex; consider carefully at what level such change must occur. To adopt a global lingua franca, it may be necessary to sell the idea to senior executives or form a coalition of technical publications groups across multiple divisions.
  • Measuring results. One difficulty is measuring results to see if the practice benefits your organization. Starting out, our team did not recognize the glossary as a best practice per se and did not plan for measurement. Learn from our mistake by defining your measurement strategy before beginning a company glossary. You measurement strategy should give you before data that you can compare with your after data. One of our strategies for improving this practice is to define and execute a measurement plan. Some ideas we have arecomparing translation costs per page before and after the advent of the company glossarymeasuring the time saved by writers who do not work on glossary definitions or research but are able to create comprehensive glossaries for their content and comparing project duration before and after the company glossary was createdconducting an extranet survey with customers about the perceived value of concepts and terminology presented in the documentationconducting a company glossary use survey within the company to measure the perceived user benefits of having consistent terminology presented across a documentation setcomparing the glossaries in documents created without the company glossary with those created with the company glossary for thoroughness, accuracy, and consistency
  • Creating a consistent process around the practice. As part of having a glossary, it is important-and often a challenge-to create a repeatable process around the creation, maintenance, and deprecation of glossary terms. To create the glossary, we follow these high-level steps (details will vary, so they are not presented here):Create terms: Identify the need, define, review, and proofread. This step requires consistent attention to the global use of the terms.A special note about this stage of the documentation process: It must be scheduled in, both at the beginning of the project and ongoing during the project as the writer develops an understanding of the subject. This stage can take a substantial amount of time because fundamental concepts are hashed out and weaknesses or holes not only in the definitions but sometimes in the organization’s understanding of the product are debated. For our organization, this stage required the buy-in and participation of a cross-functional team, including all of the roles listed in the “Roles” section of this article.Planning for intentional reuse is also critical when writing glossary terms. In most cases, we have found that terms should be written in a general enough manner to be used in any document and that such reuse requires planning as discussed in the May 2002 issue of the CIDM e-newsletter5.Maintain the tools: Open bug requests, address enhancements, and maintain your customization layer across versions (note that you do not need to do this if you use DocBook and its XSL stylesheets without a customization layer).

    Maintain the glossary: Add new terms; deprecate terms.

  • Addressing tools issues. When you have multiple documents sharing the same glossary, you may encounter versioning issues for which you will have to establish your own policies and techniques. For example, one product may use a glossary term that has been deprecated in newer products but is still referred to by another glossary term.Additionally, if you use a content-management database, your architecture may differ from the one described in this article. For example, it may be optimal for you to “chunk” a single glossary term file into individual files, one for each glossary term. We do not use a content-management database currently but would consider this chunking technique if we did.
  • Maintaining the glossary in a publishable state. Again, maintenance must be scheduled as part of the documentation process. Maintenance may include adding new terms, but just as important, it can mean deprecating terms that no longer apply to the marketing message or to the product.

Optimizations

John Henry Newman once said, “A man would do nothing if he waited until he could do it so well that no one could find fault.” Our team views best practices as an organic process. There is rarely enough time or knowledge at the outset to achieve what is possible later on. We do our absolute best and then keep improving the glossary, or nothing would ever get done.

With that outlook in mind, here is our list of optimizations to the company glossary best practice that we hope to make as time allows. You may wish to schedule these into your own glossary plan:

  • If you use XML, script the spin process (the processing of source from XML to another format) so that the location of the glossary is determined at spin time. This method is preferable because it introduces a level of indirection in the architecture so that if the glossary is moved, the transformation from XML will not fail because the glossary file cannot be found.
  • If you do not plan to generate a menu in your XML editor from the glossary term linkends as we did, you can script the spin process so that the glossary terms automatically are found during processing rather than having to be specified manually beforehand. That is, instead of using markup like this in your XML source (from the DocBook DTD):<glossterm linkend="best.practice.glossary">best practice
    </glossterm>
    as part of the transformation from XML to another format, create an XSL script to find glossary terms in your source. The XSL script automatically can add these terms to the glossary in the output (for example, PDF). In our case, we do not do this because we constrain linkends on glossary terms to create a menu of glossary terms in the XMetaL editor before any transformations to other output formats occur.
  • In the XML source, mark up glossary term candidates, and then later run a report of the candidates. Writers can use this report as a “to-do” list for glossary terms they need to write.For example, assuming we’re using DocBook, in the XML source a writer might mark a word or words as follows: <glossterm linkend="glossterm.candidate">best practice </glossterm>. Here, the words best practice are glossary term candidates (that is, they don’t have a definition yet; the writer is just marking them to set a reminder to write the definition). The writer can then run a homemade XSLT script to get a list of glossterm candidates and the context in which they were used. To create the script, you will need someone familiar with XSLT. That person may also want to write a cleanup script to remove or transform glossary term candidate markup after the definition has been written. If you automate glossary term searching and output as described in the previous bullet, you probably will not want to use linkends in this way.
  • Research the appropriateness of a content-management database for your organization.
  • Use documentation types (for example, print and online) and audience attributes (for example, DBA, application administrator, CSR, home users) to allow customers to target online content dynamically to their own needs and role at the time of the request. Customers might get a glossary filtered to their experience level (for example, DBAs would not see the definition for modem whereas home users would).

Looking Ahead

Just recently, my company merged with a long-time competitor. In legal terms, the two companies are completely joined, but the slightly differing cultures with multiple vocabularies may take longer to fully integrate. Seeing how our glossary scales from our original company to a merged company with twice as many employees (and technical communicators) will be interesting. Obviously, the glossary will require extensive change at the deepest levels of process and organizational culture. But that is the appeal of the glossary as a common language: Not only is it a byproduct of a particular process and culture but it is also a tool to shape process and culture. CIDMIconNewsletter

About the Author

April BP22

Footnotes

1 <www.oasis-open.org/committees/docbook>

2 <sourceforge.net/projects/docbook>

3 For more information on DocBook, see the O’Reilly Web page about Norman Walsh and Leonard Muellner’s DocBook: The Definitive Guide <www.oreilly.com/catalog/docbook>.

4 <docbook.sourceforge.net/release/xsl/current/doc/fo/glossary.collection.html>

5 See “Accidental Reuse” by JoAnn Hackos at <https://www.infomanagementcenter.com/publications/e-newsletter/may-2002/accidental-reuse/>