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.

What is Source Development?

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.

Source includes any programs that a company uses in house — or integrates with. Usually we think of source as software product source code. There’s more to source code than the software product. There’s documentation in the source code. There’s feature information in the source code. All of this is source for documentation development. Where can source be found? In product source code. In the marketing materials. In the price list. It’s even in the approval chain that authorizes product release.

Sometimes source isn’t obvious. Everywhere in an organization are simple tools that you don’t even know people are using. It’s in all the little ways employees track their activities and responsibilities. It’s all the things that people do to import information, but that no one even thinks of as “source.”

At one client site, a writer I knew developed a huge spreadsheet that would let him track the features that he and his team needed to document for a release. It tracked status, responsible party, due dates and engineering contacts, and other publications-specific information. He had one of these spreadsheets for every one of the five releases he was either managing or working on. In every instance, he filled out the spreadsheet by hand with tedious, strict attention to detail.

For a long time, no one knew he was doing it. Eventually, maintaining it became second nature. It provided him with an extremely accurate picture of the state of the documentation. He could respond to management’s questions easily, and he was always on top of issues the minute they arose. But he was always working late, always stressed out, because managing all this information by hand was extremely time consuming, even for all the benefit the department got out of it. His experience is not unique. These kinds of tools are everywhere in your organization. And they are always manual, time-consuming systems.

Every good management structure wants to encourage employees to automate for efficiency. If you want to make people more efficient, it’s extremely important to find these tools and create more efficient tools to improve employee productivity. By improving productivity and automatically collecting that information about information (metadata), you improve source generation.

Source is anything that inspects data and is dependent on it’s structure. Dependencies equal time lost to invisible causes anytime something changes. Anywhere. Source is just a kind of information. It is a very specialized kind of information, with specialized uses.


  • Filters and transforms information (database, statistical tools)
  • Collects information (web apps, assay machines)
  • Produces information (simulators, …)

Source code is itself a product, whether internal or external. Some parts of the source code may be aimed at internal developers, end-users, or other source developers (partners). Source code can be a driver toward information exchange in others. Businesses are driven by process, but that process can change. Ideally, processes are specified. In reality, most processes are ad hoc with guidelines.

Documentation can take advantage of levels of information, the gradations of detail, in order to produce two versions of the same manual. One version of manual may include the detailed API available to engineering while another version of the same manual might leave out the huge sections of the API that are unavailable to external end users. The varying level of detail built into the source code can drive the way that the documentation is constructed.

Where Does Source Come From?

Source is created by source makers. These people create new content that stands alone. They also create the content that gets pushed back into a product. Source is created by source annotators. The product might itself have provided metadata that was the basis for the newly-created content, in either structural or template form. Annotators take chunks of generated material, shape it, and flesh it out. Source comes from every part of the organization. Anyone who is creating or annotating source can be included in efficiency initiatives.

Efficiency is in the Tools

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.

I started off doing mostly XML and XSL development but have started working more in the advisory space — helping companies figure out what they want to do and what they can do.

Believe it or not, I often find myself trying to explain to people why they should not pursue a project. There is this bubble mentality sometimes to go ahead and XMLize everything. This doesn’t always make sense.

Consider the following Venn Diagram with three intersecting circles: CANs, WANTs, SHOULDs.

Venn Diagram with three intersecting circles: CANS, WANTS, SHOULDS

CAN you do it? Maybe.

Do you WANT to? That depends a lot on who is answering the question and why they’re motivated to look at XML at all (or unmotivated, sometimes).

SHOULD you? That’s the hard one. It mostly comes down to cost versus benefit.

It’s where these intersect — there in the middle — that I work, and for the remainder of this article, that’s where we are. Answering these gives you the answer to “what gets done?” and “how far do we go?” up front — and that can save people a lot of wasted effort, time, and money because it eliminates the problem of “invisible assumptions.”

Efficiency is in the Tools

Originally my talk was called “Efficiency is in the Tools,” but that title produced an unexpected reaction. Most people thought the talk would be a product presentation or a product set recommendation: what are the “best tools” or which vendor has the “best system.” That couldn’t be farther from the point. By tool, I don’t mean product. I mean the scripts and simple programs that join larger applications together in order to produce an efficiency of work.

I will not espouse any particular vendor, application, technology, or product. I have varying opinions on most of them, and my opinion changes based on the problem space being addressed. A product that is right for one customer may be totally wrong for another customer — even when both companies are producing similar products. There is no ultimate best. All you can hope for is finding the one that best fits your situation at this moment in time.

Situations, companies, and requirements are not static. There’s no guarantee that the requirements you have today will be the same requirements you have tomorrow, or next week, or next year. The only guarantee you really have is that all three of those things will change. No matter what system you choose — and how careful you are with your requirements when you choose it — the best you can do is to make sure that you choose a system that provides you with avenues that give you the flexibility to develop the tools that reflect your changing business needs.

This is not a new concept. Recycling content (chapters, graphics, etc.) is not new. What is new here is the common set of back-end structure in XML form and the fact that more than one set of tools — including small, mission critical custom tools — are explicitly focused on the specific needs of a given project. There is no longer any need for one tool to address all of the needs of every company that purchases a license: Single sourcing is not a tool. It is a community of tools that is easy to expand or customize without long term lock in or breaking the model.

That’s where efficiency comes from. Efficiency comes from the automation, acceleration, and merging of applications, systems, and processes that are business-specific. It lies at the edges of those same applications, systems, and processes. This is the argument that is at the core of the off-the-shelf-ware versus custom tools debate.

In a single-sourcing environment, efficiency centers around content development — source development — and its management.