Start With Technical Publications

Liz Fraley: This is the fourth of a series of articles based on the talk I gave at the Content Management 2005 conference. These articles focus on extending single-sourcing systems and activities to integrate content-generating organizations enterprise-wide.

The goal of single-sourcing is always to increase the efficiency of the entire staff as the demand for documentation increases while staffing and resources do not. The benefits for publications have been well covered in the last few years.

Single-sourcing objectives include:

  • Making reuse possible
  • Improving accuracy (fix once, fixed everywhere)
  • Improving quality (more time per writing unit means greater quality)
  • Increasing author collaboration
  • Automating simultaneous delivery of source material to multiple media
  • Reducing translation efforts and costs

Single-sourcing benefits include the separation of form from content. In some ways the desktop publishing revolution of the 80s could be considered a detour. In the 80s, writers for technical information ended up being given the additional task of adhering and enforcing “presentation” — something that was not their job and is not relevant to the actual task of writing. XMLized single-sourcing brings with it a return of the focus on content to writers while at the same time providing them with a much richer language for self-(content) expression. Think of “bold face” as a pidgin language way of marking something as important.

The Desktop Publishing (DTP) revolution of the 80s was a positive change. The education needed to use the applications was greatly reduced by the instantaneous visual feedback to the user and the coincident ability to experiment and explore the capabilities of the tool. It allowed the rapid production of finished documents by those who were generally unschooled in the basics of typography and layout. Writers could subsume the role of dedicated layout technicians.

This change was not free: the long term cost of the 80s-style DTP approach to document creation is that the resulting documents are by and large isolated from the larger pool of documents and the information used to create them. Even simple issues are complex: if a company logo changes, each document has to be re-worked, if they can be re-worked at all. This is often an issue when the applications evolved and lost compatibility with old document formats.

With the 80s and early 90s DTP, the productivity upside at the front end of the process is lost at the back-end as the lifetime of the content is extended and larger projects attempt to adopt the same tools. This behavior can be seen as different distributions of effort and cost: Some tools have high front-end cost but are very efficient for ongoing projects where the content will change over time and others have a very low front end cost but such a high back-end cost that the projects that use them will inevitably be restarted from scratch. It’s the difference between front/back end vs. front/back loaded.

Single-sourcing attempts to return content generation expertise to authors, return formatting expertise to format experts. It lets authors focus on correct, collaborative development. When something is added, someone knows. When something is deleted, someone knows. Tools that monitor single-sourcing systems can automatically red-flag things in process. Because individuals are freed from devoting attention to processes that tools monitor automatically, their attention is not divided or redirected away from their primary activities. As a result, documentation organizations can achieve faster development.

In some cases, tools can automatically generate content or content templates. At Juniper Networks, some volunteers from the engineering organization put together a tool that would generate the chapters for the System Log Messages book. The build process would walk through the system log messages and generate one XML chapter for every set of related log messages — straight out of the source code. Authors could drop the generated XML chapter right into the larger XML document and proceed to publishing. Authors guaranteed the readability of the log messages by editing the source code files. By working directly with the software source code, the log messages were readable by the software product users as well as the documentation readers.

How Do I Go Beyond Technical Publications?

It’s easy to get people to add something if there is no serious burden and the task is “in line” with work they’re already doing. It’s hard to get anyone to add anything if the work is obviously additional.

No amount of process can solve this in the real world. Water flows downhill. People do valuable “optional” work all the time. People will not work extra hard to “do it right.” If you make it hard, you get less. But if you keep data local, all kinds of opportunities for integrating with other parts of your business open up to you.

Get useful tips and valuable resources every month

Join the thousands who know just how much we share.

Powered by ConvertKit

Author: Liz Fraley

Liz Fraley