No one system that works for every customer. No one book describes how to put it all together. Although we do this all day, every day, here you will find places that will help you figure out where to start.
One of our goals is to help customers make the choices that will allow them to implement a system that scales. Necessarily, for any concrete project we must choose a set of tools and we must decide how to implement particular components.
At Single-Sourcing Solutions, we've used nearly all the tools out there and, although we're an Arbortext partner, we know it isn't for everyone. More importantly, we avoid unnecessary customization, so that our customers can take advantage of new products and new technology down the road.
The Single-sourcing triangle includes the Information Management folks (theory), the Programming folks (technology), and the Vendors (products).
The Theory Side: The Information Management Consulting Companies
There are a lot management consulting companies who specialize in best practices: the theory of single sourcing. Their literature is full of information about strategies, document design techniques, and how to choose a tool or evaluate a product. These companies work to create standards and generalized rules for making single-sourcing work in traditional publishing environments. These companies have excellent information on their websites about how to get cost savings through single-sourcing, how to write modularly, or how to structure your documentation.
When you're first learning about single sourcing, you can't find better resources:
- S1000D Technical Publications Specification Maintenance Group (TPSMG) is responsible for the development and maintenance of the ASD/A1A S1000D international specifications. S1000D describes a standard for the creation and publication for technical publications utilizing a common source database
- The Center for Information-Development Management provides "a focused, expert, and progressive forum to support documentation, training, and customer service managers in creating high performance teams that produce effective and appropriate deliverables."
- Members of the Rockley group work with clients to develop "information solutions through a unified content strategy, either for a particular project or across an enterprise. "
- Single Sourcing: Building Modular Documentation by Kurt Ament This is one of the only books that attempts to bridge the gap between the single-sourcing theorists and the technology developers.
Hackos, Rockley, Ament are, to a significant extent, the existing authorities in theoretical single-sourcing and information design. Their websites have everything the beginning single-source-er 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 this side of the triangle is that nearly all of the literature 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.
Most of the single-sourcing literature is aimed at writers or managers. As an implementer, I am hired to design, recommend, and implement not to manage. I've done the internal, upwards selling. Mangers looking to implement single-sourcing must understand the point of it all, so they can sell it — to their managers and their people — for the project to succeed. And that's how it should be.
However, what is not aimed at managers is aimed at writers: guidelines for writing and designing modular documentation. 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 look for as an implementer. These books continue to be essential for training the writers to write and think modularly.
What these books are missing, however, is the rest of the triangle: The components that bridge theory and practice. And they’re not alone.
The Technology Side: Programming Nuts and Bolts
The technology companies focus on XML as a programming language.
The methods for code reuse, found in Object-Oriented programming literature, are similar to the methods used to achieve modular writing. 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.
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.
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. There are lots of books and online resources. The only problem with this side of the triangle is that nearly all of the literature is technical in nature. Most books on XML contain information about programming XML applications—from programming XML compilers to web-services. At this, they are very good.
But this group too is missing the rest of the triangle: The components that bridge the nuts and bolts of technology and real-world practice. And, once again, we find that they are not alone.
The Product Side: Vendors and Application-Specific Specialists
Product companies focus on developing full product suites to cover every possible customer. Their literature focuses on amazing application-specific features and why their products are the best choice for any environment. These companies work hard to sell products and consulting services to implement their full-scale systems.
Several vendors sponsor think tanks and white papers that help implementers understand the components to any single-sourcing system. Many provide resources for information on single sourcing and XML. Often these resources surpass the boundaries of their product line.
The only problem with this side of the triangle is the problem that faces nearly every vendor.
Competition is fierce. Products and implementation strategies are expensive (even if you DIY) and generally generic. Depending on the product, it can take a considerable amount of customization before you have any sort of working environment. These companies do their best to make sure their products fit your requirements—rather than making sure that your requirements fit their product suites. It's a rare vendor indeed that recommends a competitive product instead of one of their own.
In the end, with any of these companies, customers will get an implementation that works. They all have professional services that provide expert implementation assistance. So, at that, they are very good.
But this group too is missing the rest of the triangle. Often solutions are awkward and don't scale well to meet changing requirements as companies grow: they're focused on sales rather than the general theory and technology that are essential for a well-designed customer-specific solution. They miss the application-specific opportunities where documentation meets source development because they're designing a system for the here-and-now.
So again, we find that they are not alone.
The Complete Triangle
Attempting single sourcing with help from only one side is a recipe for disaster:All three sides of the must work together to create a solid foundation for your project. Successful single sourcing requires competence and execution on all three sides:
First, the information itself (the content) must have real structure. Information management consulting companies can help your various writing groups organize their content and think about it in new ways that promote single-sourcing activities.
Second, you need software engineers and IT folks to make sure that both the hardware and software infrastructures support single-sourcing activities.
In addition, these folks must work closely with the vendors (Side #3) chosen through rigorous requirements matching, to make sure that all the different systems play well together. Over-engineering your triangle (excessive customization) will produce systems that prevent you from extending your single-sourcing system to interact with other business entities, essentially stifling any future process innovation.
Understanding the triangle is essential, but you cannot stop there. The triangle exists in time and space: it lives, breathes, and survives in the context of your business. The triangle is the foundation. When you understand how each side the triangle fits the goals and needs of your business, you've guaranteed your success.
Ament says it best: “Single sourcing is a methodology, not a technology.” XML is a technology, not a methodology. Bringing it all together is not obvious or well-defined. 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.
Customers spend large amounts of money, resources and effort but don't get the system they expect. You should research all three sides of the triangle and do a lot of planning at the start. Only then will you get a complete, extendable, and workable solution that benefits their entire company and sees return-on-investment from the very beginning.
Our experts have implemented successful solutions by paying attention to all three sides of the triangle. We present often at conferences and have written papers about our previous experiences. And we teach our customers to do it as well. We're also one of those rare vendors who will look at your whole organization and let you know—absolutely and without question—whether or not Arbortext is a strategic fit for your business. Don't be surprised if we tell you no. We've been known to do just that.
Get a second opinion
Want a second pair of eyes to look over your plan, your requirements, and your list of vendor questions? Want more (and better) questions to add to your list? Talk to one of our consultants and benefit from the thousands of implementations we've participated in. Schedule an Independent Validation and Verification session.
References
[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.
Note: When you purchase something after clicking links in our articles, we may earn a small commission. Read our affiliate link policy for more details.