Search icon Looking for something?

Key Content: The Documentation Elephant
2004, Q3 (July 05, 2007)
By Bill Albing, Michelle Corbin, and Ann-Marie Grissino

Clipart of elephants


As we grapple with the changing processes and tools with which we work, we are evolving from technical writers into content developers. This evolution requires a new vocabulary, one that borrows from the vernacular of various industries. Even though many of the phrases in this vocabulary appear to refer to different and distinct things, they really describe different aspects of the same work. This article pulls together these phrases and explains the single effort, reducing the complexity of enterprise communication. Sifting through these phrases echoes the fable of the blind men examining the elephant-each man who put his hands on a different part of the elephant had a very different experience, and a different name for what he was handling.

As technical writers, we work more online than ever before. We are beginning to work with documentation in a new way, so that we can repurpose content and free it from the restrictions imposed by any particular delivery mechanism. We no longer solely create paper-publishable documents. We do not, as yet, have a good word for what we do; we do not have a single word or phrase that summarizes the effort or the deliverables. Nor can we use any single existing lexicon because the concepts are new. This difficulty is a natural consequence of the inter-networked world in which we work, where information is delivered multiple ways for diverse audiences. But let us look at the phrases currently growing in popular usage that refer to this effort.

Views of the Elephant

One of the more popular phrases, gaining in usage many places, is "single-sourcing". This phrase is used when the emphasis is on delivery to multiple outputs from a single set of inputs. It is a way of saying that by putting content into a single data base or program, multiple outputs can be created, such as a printable manual or online help, from a single source of content. Some use the phrase "information reuse," when the emphasis is on managing the content, almost as if it were data, to allow reuse and repurposing.

Some use the phrase "structured authoring", a broader category for focusing on content and not presentation, when the emphasis is on the structure imposed by having content fit certain rules that defined by the types of information. This is also referred to as "XML authoring," a specific type of structured authoring, focusing on XML tagging or implementation.

Some use the phrase "content management", focusing on business, productivity, and how to deal with source material, when the emphasis is on managing the content, almost as if it were data, to allow reuse and repurposing. This also emphasizes information typing, focusing on content, but is used as a way to achieve many of the other items discussed here. Focus on content management typically involves expensive, centralized systems.

Some use the phrase "information modeling", focusing on designing the content, when the emphasis is on the overall process of creating a user deliverable from the raw material of content using an architecture from the user's perspective. This is also referred to as information architecture, focusing on designing the overall view of the information. Information architecture is lying out the user tasks, user goals, user interactions and considering what content is needed and how to deliver that content. Then, from a content management perspective, the information is "chunked" into different types-such as concept, reference, and task. Information typing facilitates single sourcing and information reuse, but that is not in and of itself information architecture. The architecture is the bigger, more complete perspective and vision, whereas content management is a way to manage content pieces within an architecture.

All of these terms should be user-focused, but sometimes the authoring aspects keep us from thinking of the user first and instead put the technology first Some of these terms focus on the user, but often downplay the technology or the capabilities, to the detriment of the writer.

Some use the phrase "XML authoring" when the emphasis is on the use of XML to tag or "type" content. XML is one medium for "single-sourcing" and structured authoring.

We see information architecture and information modeling as similar in that they are organizing and architecting information with output delivery mechanisms in mind. Content management seems to us as the management of information, maybe a slightly different view of the initial architecture. Maybe it's more of a managing of all the discrete pieces. And maybe structured authoring is a type of information architecting. We think of information architecting as a range from the mere organization in an outline and chunking topics and thinking about informational elements to architecting with XML and non-XML solutions in mind. The XML version would of course need structured authoring. In other words, none of these are really separate disciplines or projects; they're simply separate views of the same overall discipline or effort. Taken to extremes, any view would make the project lopsided.

But all these terms depend on a set of rules or definitions about the type of information, and so we use the verb phrase "information typing", and with XML we say "tagging". Just as with the advent of "word processing" before, "information typing" is not one tool or one industry. It's all about discrete modules of content that can be managed, reused, and re-purposed. It is about the technical communicator helping to define the types of information and not just creating print-ready documents. It is a general family of tools and imposes a particular type of workflow based on its capabilities. In the '80s and '90s, we used word processing and desktop publishing. Now we have a new generation, not just of tools, but of processes and workflow. In the current enterprise, we are still developing the terminology, but we are talking about the same communication effort.

These concepts are linked and maybe are just slightly different perspectives on the same overall topic. While they are certainly not identical, there is some overlap of each of them. They all describe the same new reality — a new work environment for technical communication — while emphasizing different parts. Like visually restricted technical writers all describing the same next-generation documentation elephant, we are developing words that describe our piece or our focus. Because we are so focused on our daily work, we can benefit from stepping back and seeing the big picture. Let's keep the discussion going.

Bill Albing is a past president of STC Carolina. He can be reached at albing at mindspring dot com. Michelle Corbin is a past president of STC Carolina. She can be reached at corbinm at us dot ibm dot com. Ann-Marie Grissino, who has been STC Carolina Competitions Coordinator as long as anyone can remember, can be reached at amgrissino at keypointconsultants dot com. End of article.

More articles like this...
Comments powered by Disqus.