Revision of Resources for Single-Sourcing Projects from Sat, 2008-08-30 00:45

Single-Sourcing Blog

About Arbortext, DITA, and bringing the two together.

Folks starting single-sourcing projects are faced with insufficient resources. The biggest 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.

I have found that most of the single-sourcing literature is aimed at writers or managers, not implementers. I created this list when I was hired on my first single-sourcing project. I was hired to design and implement not to manage. I wouldn’t be selling upwards: my director was championing this project throughout the company. Someone else would be doing that. Someone else would be determining ROI and measuring success. Nor was I the project manager, even though I would help determine which tools we eventually choose.

What is not aimed at managers is aimed at writers: guidelines for writing and designing modular documentation. This is something else that 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 is nearly as bad. The XML programming book that 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, the programmer-oriented 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.

I have never found the one book that describes how to put it all together. You make choices—good and bad—along the way that influences the way you implemented particular pieces. You choose a set of tools. You do as much or as little customization as you're comfortable with and as your goals require.

My goal has always been to provide specific examples that can serve spark ideas to solve someone else’s real problems. That is the best any case study can do: Give you an idea about what you can try. Hopefully, all together, these resources will help bring your project into focus.

To this end, I've put together the following lists:

  1. Top 6 book choices
  2. Top 10 online resources
  3. Top 4 resources for Arbortext users.
XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I