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.

Practical XML Development

Liz Fraley: This is a new blog and this is the first post. Although I’ve been an avid reader, I’ve never been an active poster on the boards or newsgroups over the years. I’ve also come and gone as a reader, looking for specific information, but I’ve never blogged before. I never really saw the point. Until now.

My intent here is to create a blog of everything I know about:

  • single-sourcing: code, definition, help, documentation
  • application-specific xml tools development
  • practical XML development and deployment

My goal is to create a place where other people doing the same thing in other places can ask questions, seek answers, and help us all grow knowledge together.

I went from zero to 60 in about 2 seconds, so I never managed to get everything down.  If you find it useful, great.

I hope that at some point there will be enough content here that someone starting out can actually get started and that the rest of us can improve what we have already done.

Setting up a single-sourcing system. It isn’t hard; it isn’t new. Yet still, the knowledge about exactly how to do it is hard to come by.

The real problem is that there are no practical resources on the subject. No books. No articles. The only way to learn it is to work for a company that specializes in doing it. This means that either you work for one of the vendors who services a part of the space or you work for one of the consulting houses that specializes in the general development side, and you learn how.

If you try to do it yourself, the closest you get to real “how-to” information are either articles by and for XML programmers or you get articles by and for managers and documentation people. The engineering books and articles give detailed explanations about how XML works, how to implement it, and XML specifications.

The documentation books and articles tell you how to use the systems effectively. Neither one tells you absolutely anything about putting the two sides together. With the documentation/manager folks, you get docbook and DITA implementation stuff, but that’s limited in it’s own way: it’s only about writing the documents with that particular DTD, not about the overall system.

The documentation that describes how to do it and what needs to be done to bridge the gap between what you get from the engineers and what you get from the doc folks is completely and totally missing.

The consulting houses count on that. Only, they don’t teach their customers to do what they do, they come in and do it for them.

I learned how to do it the hard way[1]. It took me 10 months to come up to speed working with an independent consultant, who’d worked for one of the larger houses. She’d implemented simple systems several times. We only contracted with her for 40 hrs/MONTH. She did the beginning steps for us and answered questions for me. Basically, she gave me the breathing room to learn it. I was lucky. I learned from someone who was willing to share, early on. I was unlucky later when I had to learn the rest when I was smack in the middle of it all.

However, because I had to learn it the hard way, I decided that I’d do the same for other people that she did for me: teach people how to do it. I also decided that I’d do facilitation work to help other people learn how figure out what they’re trying to accomplish with XML and to do it successfully.

About Single-Sourcing Solutions

  • We do implementation
  • We do mentoring
  • We do training
  • We do evangelization — our Information Development Assessment can help you sell your project internally
  • We help companies develop an overall XML strategy, across all kinds of business units and business functions

We also give presentations on how to implement this technology in various parts of your business (not just pubs). We hold customized seminars on how you can implement coordination between your groups based on XML technologies and fold systems together.

[1] 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.

About Single-Sourcing Solutions

At Single-Sourcing Solutions, our focus is on customers who, for one reason or another, prefer to pursue an in-house or limited-resource-based implementation rather than a fast, large-team implementation. We focus on acting as mentors or as part-time resources to assist implementers while they’re getting started.

We help in-house teams learn to do it themselves by providing an on-call resource that can assist as necessary.

  • We teach people how to do document analysis, so they can do it themselves, one book at a time, as their staff has time to devote to the project.
  • We can act as a jump-start team, doing initial stylesheet development or tool implementation with the intention to hand it over to the in-company team as soon as they feel ready to take it over.

Our approach is to provide honest, direct advice — and just the right amount of assistance — to take new Arbortext customers from purchase to production.