Single Sourcing: Building Modular Documentation

Scott Abel writes "Kurt Ament has hit the nail on the head! His latest effort, Single Sourcing: Building Modular Documentation is a valuable reference for those of us who seek to save time, effort, and money by implementing a productive method of creating information once and reusing it often." It's not a big book -- just 246 pages. Read on for Abel's brief review. Single Sourcing: Building Modular Documentation author Kurt Ament pages 246 publisher William Andrew Publishing rating 10 reviewer Scott Abel ISBN 0815514913 summary How to build modular documentation you can re-use in different formats for different audiences and purposes Ament covers the issues -- step by step -- that many others only discuss. He lays out a simple roadmap, complete with real world examples that have worked -- or not worked -- for his clients.

In Chapter 1 (About Single Sourcing), he carefully defines "single sourcing" and explains related concepts (reusable content, modular writing, and assembled documents) in ways that are easy to understand and free of techno-jargon. And, he does us all a big favor by addressing the negatives associated with using technology to assemble documents by explaining that it actually takes more creativity to write content that can fit into multiple media, for multiple audiences, than it does to continually rewrite information over and over again each time it is needed.

Chapter 2 (Building Documents) and Chapter 3 (Structuring Content) are of particular value to those seeking to understand the shift in thinking required to master single sourcing. Writers, programmers and managers will all benefit from these chapters. Each chapter is packed full of tips and examples you can begin using today!

Chapter 4 (Configuring Language) explains how to "configure" your writing to support and increase usability while Chapter 5 (Leveraging Technology) touches on issues including conditional text, conventions, localization, translation, variables and more. As are the previous chapters, Chapter 5 is written in clear, concise language and is not a chapter business types should skip. In fact, it's just the opposite. Managers and decision makers need to understand the concepts explained in this chapter because many of the benefits a single source strategy can deliver are made possible by combining good planning with the right technology. And, while this chapter is certainly not about selecting software tools, the author helps his readers understand some of the issues they will need to understand as they begin thinking about their strategy and the types of functionality they'll need to support with the tools they select.

What I like most about "Single Sourcing" is that Ament went straight for the meat of the issues. He doesn't belabor points or confuse the reader by jumping back and forth from subject to subject (as so many poorly written IT-related books do). Instead, he supplies us with a book you can read in an afternoon and use the information contained within the next day at work.

But, be forewarned. You're going to want your sticky notes and your highlighting markers nearby. Chances are you'll be using them a lot!

Other resources:

• Kurt's site: http://www.infotektur.com
• Book site: http://www.infotektur.com/books/singlesourcing/ind ex.html

Scott Abel (abelsp@netdirect.net) is a content management strategist who assists his clients in planning and preparing for content management initiatives. Scott is a frequent presenter at industry and professional service seminars, an instructor at Indiana University Purdue University at Indianapolis Community Learning Network, and vice president of the Society for Technical Communication (STC), Hoosier Chapter. You can purchase Single Sourcing: Building Modular Documentation from bn.com, though new copies are currently out of stock. Slashdot welcomes readers' book reviews -- to see your own review here, read the book review guidelines, then visit the submission page.

Comments

Creativity?

[chmod000]

And, he does us all a big favor by addressing the negatives associated with using technology to assemble documents by explaining that it actually takes more creativity to write content that can fit into multiple media, for multiple audiences, than it does to continually rewrite information over and over again each time it is needed.

This would seem to be more of a reason to avoid modular doco. Creativity is not, shall we say, plentiful? at the typical workplace. And often, it isn't wanted when it is available.

make ambigeous

[Anonymous Coward]

./configure --enable-mod=ambigeous
make
make test
make install

use XML

[stonebeat.org]

use XML. provides re-use of content. no big deal. and now there are collaborative XML editors, which allows authors to work on various sections of the same document.

246 pages is not big?

[Junks Jerzey]

I guess we've all gotten used to artificially inflated monster technical books, where it's expected that Learn Java 2 in 24 Hours needs to be 950 pages or it's crap.

Here's a clue: Those big books are hugely padded by:

1. Large margins so there can be a little note every few pages.
2. Repeated program listings, also with huge margins.
3. A hundred or more pages of fluffy introductory chapters ("What is a programming language?").
4. Massive redundancy.

Personally I'm waiting for the return of slim, readable books.

turning point?

[voixderaison]

This review was stimulating, and filled me briefly with hope, then I crashed after pondering a bit. I'd like to think that we could look back on this someday as a turning point of some sort, perhaps the foundation of a new engineering discipline of documentation. Of course, lots of people thought (and probably still do) that SGML was the foundation and now we're building walls. And maybe it was, but SGML (and the derivatives HTML, XML, and future arbitrary useful DTD to come) suffer from some problems - external and cultural mostly. The technologies are somewhat complex, and there is a general lack of understanding about how to apply the technology to advantage.

The core concept of arbitrary display and formatting of structured text, which appears to underly this new work, remains alien to most of the people making business decisions and authoring documents. When you combine a vacuum style lack of good tools to author documentation in the target technology with a flood of readily available "old paradigm" authoring tools for making stuff look pretty (word processors and desktop publishing stuff) you get the explosion in documents that was seen in the 90's. You also get the tremendous resource drain as these docs are updated and reformatted for subsequent generations of word processor formats that continue to mix content and presentation. We also see a direct parallel problem with the amazing fanatical market success of programming environments where logic and presentation are mixed (MS.asp, PHP, etc.) over object oriented tools. Far, far more dynamic web sites are built "the old fashioned way" despite the availability of decent, even "better" authoring tools that exist in the object oriented world.

Unfortunately most organizations that produce and use documentation do so as an aside at best, or an afterthought at worst. Organizations typically don't value documentation highly enough to create job descriptions for skilled technical writers. Corporations with IT staffs of hundreds of people - managers, systems administrators, help desk workers, developers -- often don't have a single Technical Writer.

Take the help desk as a primary example. Just about every big company produces volumes of documentation for use by the help desk workers. Sadly, much of that documentation is created after the fact, by desperately struggling front line help desk workers themselves, who randomly try to assemble facts and myth about problem resolution. The folk creating the systems are generally not given sufficient time to develop and maintain documentation, often barely enough resources to develop the system in the first place, before moving to the next task. It's rare for companies even to realize the blatant "in your face" opportunities to save money by investing in better documentation.

If we can't get developers to understand this basic concept, how can we get front line help-desk workers who are writing documentation for themselves out of desperation and under the clock of "you still gotta answer twenty calls an hour and resolve 19 of the problems before hanging up"? Even better, how do we get a bureaucratic organization to invest in skilled technical writers?

It seems to me that to get to this point we will need to create authoring tools that are so powerful and easy to use that the authors of documentation don't need to think about the separation of content and formatting -- it "just happens" in the background. Anybody who writes such a tool gets to spend the rest of their life retired on a beach, earning twenty percent and drinking rum from hollowed out pineapple shells with little paper umbrellas in them.

Re:turning point?

[jolshefsky]

Just to spin what you've said--I think it's very sad that the organization of information is the afterthought in most documentation projects. The first question everyone seems to have is, "should command names be in Courier or Arial?" Come on ... if you're staring at the prospect of handling some quantity of information equivalent to (at a minimum) hundreds of pages of printed text, don't you think it should be your first priority to get a handle on how to organize that information?

I'm mired deep in that territory now. I am desperately trying to attack the problem from the wrong side--I'm starting with our established desktop publishing package and trying to define meaningful styles that could be used in the future for content parsing.

The battles I fight are so far removed from what's important, it makes me miserable--our document templates actually include a style called "Bold," for instance. Bold??? Why define the style at all if it's a built-in function? In programming C, it's like defining "TRUE" to 1 so you can write comparisons like (x==1)==TRUE instead of (x==1)==1. Whether you define a "style" or just click the little "B" icon, it's the same problem.

The fact that we're using a desktop publishing package at all for data entry should be at issue--why not an editor to enter content in a hierarchy which will later be rendered by whatever appearance template we chooose? I wish I had a reasonable chance of ditching the desktop publishing package all together for something more pertinent.

I think that like you, I'm also looking forward to the industry of documentation--or more likely--information organziation and presentation. I just hope I'm not dead first.

Re:Documentation professionals are creative

[Tsu Dho Nimh]

I somewhat agree ... i've worked on a few projects where the management had a wild idea that we could create content that could be used for web pages, user manuals, maintenance manuals, etc. with no further human intervention ... they had not thought about the limitations of the presentation medium. Realistically, the best you can do is create "chunks" that are easy to recycle because they are not contaminated with irrelevant information, have a consistent style, and do not depend on outside infomation.

Full Disclosure Please

[entropy_uc]

I would find these reviews a lot more useful if there was more disclosure of the reviewers biases.

How do I know the author isn't benefiting from writing his glowing review here in some way? I'm not accusing the reviewer of any misbehavior here, but when the only negative of a book is that "But, be forewarned. You're going to want your sticky notes and your highlighting markers nearby" I have to question the bias of the reviewer.

Sample review checklist
1. Have you contributed to this book or been cited within the text?
2. Do you have a personal or business relationship with the author(s) or publisher?
3. Do you sell services related to the books topic?

Single sourceing: Tech Writing's Newest Boondoggle

[tres]

Sorry, I've seen first hand "single sourcing" hard at work. It's the biggest boondoggle since the "synergies" of the late nineties.

Writing good documentation is hard work. It seems to me that the only people who benefit from "single sourcing" are the people who are writing these books and giving overpriced lectures to rooms full of unemployed tech writers.

Ultimately it won't improve the clarity or usefulness of your documentation. It won't provide you with the ability to understand the subject or the audience any better.

Don't get me wrong, if there were a magic-bullet that single source claims to be, I'd be all for it. It would be nice not to have to worry about document formatting. But personally, I think it's simply another way for organizations like STC (The Society for Technical Communication) to filch money from their members.