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.

For example, it’s not about 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. Although I'm involved in the upwards selling, but I know that it's the internal people who matter. 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 managed to find one system that does everything. And 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. 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.



Technorati Tag: single-sourcing

Practical XML Development

Liz Fraley: This is a new blog and this is the first post.  I've never been active on the boards or newsgroups over the years. I've come and gone as a reader, mostly 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 company that specializes in doing it. This means that either you work for one of the vendors who services a part of the space (Arbortext, Documentum, Oracle, Astoria, XyEnterprise) or you work for one of the consulting houses that specializes in the general development side (Flatirons, Innodata-Isogen, DMSI, Scriptorium, Single-Sourcing Solutions), 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. It took me 10 months to come up to speed working with an independant 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, Inc.

• We do XML implementation

• We do XML evangelization!

• 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 hld customized seminars on how you can implement coordination between your groups based on XML technologies and fold systems together.


Technorati Tag: single-sourcing