Efficiency is in the Tools

Liz Fraley: This is the fourth of a series of articles based on the talk I gave at the Content Management 2005 conference. These articles focus on extending single-sourcing systems and activities to integrate content-generating organizations enterprise-wide.

I started off doing mostly XML and XSL development but have started working more in the advisory space — helping companies figure out what they want to do and what they can do.

Believe it or not, I often find myself trying to explain to people why they should not pursue a project. There is this bubble mentality sometimes to go ahead and XMLize everything. This doesn’t always make sense.

Consider the following Venn Diagram with three intersecting circles: CANs, WANTs, SHOULDs.

Venn Diagram with three intersecting circles: CANS, WANTS, SHOULDS

CAN you do it? Maybe.

Do you WANT to? That depends a lot on who is answering the question and why they’re motivated to look at XML at all (or unmotivated, sometimes).

SHOULD you? That’s the hard one. It mostly comes down to cost versus benefit.

It’s where these intersect — there in the middle — that I work, and for the remainder of this article, that’s where we are. Answering these gives you the answer to “what gets done?” and “how far do we go?” up front — and that can save people a lot of wasted effort, time, and money because it eliminates the problem of “invisible assumptions.”

Efficiency is in the Tools

Originally my talk was called “Efficiency is in the Tools,” but that title produced an unexpected reaction. Most people thought the talk would be a product presentation or a product set recommendation: what are the “best tools” or which vendor has the “best system.” That couldn’t be farther from the point. By tool, I don’t mean product. I mean the scripts and simple programs that join larger applications together in order to produce an efficiency of work.

I will not espouse any particular vendor, application, technology, or product. I have varying opinions on most of them, and my opinion changes based on the problem space being addressed. A product that is right for one customer may be totally wrong for another customer — even when both companies are producing similar products. There is no ultimate best. All you can hope for is finding the one that best fits your situation at this moment in time.

Situations, companies, and requirements are not static. There’s no guarantee that the requirements you have today will be the same requirements you have tomorrow, or next week, or next year. The only guarantee you really have is that all three of those things will change. No matter what system you choose — and how careful you are with your requirements when you choose it — the best you can do is to make sure that you choose a system that provides you with avenues that give you the flexibility to develop the tools that reflect your changing business needs.

This is not a new concept. Recycling content (chapters, graphics, etc.) is not new. What is new here is the common set of back-end structure in XML form and the fact that more than one set of tools — including small, mission critical custom tools — are explicitly focused on the specific needs of a given project. There is no longer any need for one tool to address all of the needs of every company that purchases a license: Single sourcing is not a tool. It is a community of tools that is easy to expand or customize without long term lock in or breaking the model.

That’s where efficiency comes from. Efficiency comes from the automation, acceleration, and merging of applications, systems, and processes that are business-specific. It lies at the edges of those same applications, systems, and processes. This is the argument that is at the core of the off-the-shelf-ware versus custom tools debate.

In a single-sourcing environment, efficiency centers around content development — source development — and its management.

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.