Bridging the Single Sourcing-Development Gap

Liz Fraley: In the past several years, there has been much theory about single sourcing, but not enough practice. The literature is full of information about single sourcing from a theoretical perspective. So, this blog is more about what isn’t covered in the literature than what is[2].

For example, it’s not about why you move out of traditional publishing, how to choose a tool or evaluate a product, how to code XML, how to get cost savings through single-sourcing, how to write modularly, or how to structure your documentation. And it isn’t about amazing product features that I’ve used or developed over the years when implementing single-sourcing systems.

Most importantly, this blog is not a set of generalized rules for making single-sourcing work. It is one long a concrete example because, in the end, that is what the developer of a single-sourcing system needs to see. And interestingly enough, it’s what the users of that single-sourcing system need to see, too

The Single-Sourcing Literature

For all of the topics that I am not covering, the existing authorities—Hackos, Rockley, Ament—have everything the beginning single-sourcer could need. Their books (and conferences) are extremely useful. They are full of detailed information to teach managers, writers, and document designers how to think about single sourcing.

The only problem with the existing literature is that nearly all of it is theoretical in nature. Most books on single sourcing contain advice about planning, managing, and creating modular projects and documentation. At this, they are very good. What they’re all missing is the bridge between theory and practice. And they’re not alone.

Most of the single-sourcing literature is aimed at writers or managers. As an engineer, I am hired to design, recommend, and implement not to manage. I’ve done the internal, upwards selling. It’s these internal people who matter most. If they understand the point of it all, then they can sell it — to their managers and their people — and the project will succeed. Companies continue to grow; the demand for documentation increases while staffing and resource challenges persist. I’m the one writing the documentation that determines return on investment (ROI) and measuring success for the managers to pass upwards and get credit for.

And that’s how it should be.

However, what was not aimed at managers was aimed at writers: guidelines for writing and designing modular documentation. This is something I would not be part of and should not be. The writers who would be using the single sourcing system would be planning their documentation, just as they always did.

This sort of information was valuable as a look at the point of view of the user, but it wasn’t what I was looking for as an implementer. But I knew that these books would be essential for training the writers to write and think modularly.

The Programming Literature

The way that modular writing works is very similar to methods for code reuse found in Object-Oriented programming literature. Code reuse is the assertion that if you build generic objects they can be used and reused. It is the idea that you can isolate functionality into a module (function) and then use that module rather than rewriting the code. The ideas are the same.

Unfortunately, the programming literature faces the same implementation gap, from the other side. The XML programming books, which don’t describe its implementation as a language, describe the multitude of ways you can use XML. They tell you how to write the XML and how to process it: They do not tell you how to make XML work in a single sourcing environment.

In addition, these books are not aimed at either of the groups that the single sourcing documentation targets. XML authors assume their readers have a programming background and already understand programming concepts.

Bridging the Gap between Single-Sourcing and XML

Ament says it best: “Single sourcing is a methodology, not a technology ” [1]. XML is a technology, not a methodology. Bringing the two together is not obvious or well-defined.

Many companies try to sell systems that bring it together. But in the end, “to ensure success, develop local, project-based standards for modular writing. Base your standards on what actually works in your own projects” [1].

I’ve never found one book that describes how to put it all together. Software development is decision making: We make choices—good and bad—along the way that influence the way we implement particular pieces. We choose a set of tools. I prefer to avoid customization at all costs. I prefer a system that uses small mission-critical tools to bridge system components together or does that work for me. That way, I can drop any vendor at any time and all I have to change is the bridge.

You make decisions; you live with them. Hopefully, you also learn to make better decisions and learn how to improve the situation created by the worst of the ones you made.

When I started this project, I went looking for the information in the middle: the information that joined the single-source theory to the XML implementation. In the end, I learned how to create that information.

Much of what I’ve learned has been useful to me now that I’m doing this again somewhere new. I love it. I love seeing old technologies applied to new domains: Technical documentation discovers object-oriented concepts in a real, practical way. It’s great. This is what I got into programming for in the first place.

-:-
[1] Ament, K. Single Sourcing: Building Modular Documentation. William Andrew Publishing, Norwich NY, 2003. ISBN 0-81551-491-3.
[2] Fraley, Liz (2003-10-15). Beyond Theory: Making Single-Sourcing Actually Work. New York, NY: Association for Computing Machinery. pp. 52-59. ISBN 1-58113-696-X.

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 https://www.linkedin.com/in/elizabethfraley/