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

Will they read the finer manual?

[SourceHammer]

It seems that no matter how much I spend creating documentation, the users of the system don't use it, don't know how to access it, won't use it.

I say take your money and buy a book on user interface design. The problem is not how well written the docucumentation is; it is the fact that we NEED the documentation.

Re:Will they read the finer manual?

[john82]

Although what you say may be applicable to user interfaces, that is just a fraction of the documentation to consider. I can think of any number of proposal documents where we take a modular approach to sections: it's called boilerplate. When you have several proposals in the same line of work there's a lot of cut and paste from submission to another. On individual projects there are system design specs, operations & maintenance manuals and more. Your assertion does not apply in these instances.

Re:Will they read the finer manual?

[Smidge204]

I believe the quote goes... "Documentation is like sex. When it's good, it's really good. When it's not, it's better than nothing."

It's all fine and good to make a great looking and intuitive UI whenever possible, but there's a lot of times when no matter how good a UI you make, the type of program (or device) it is will simply NEVER be intuitive enough to survive without some kind of explaination for what various widgets are for or what various errors/messages/etc mean.

The problem is many people hear "documentation" and imagine 300+ pages of legalese descriptions. Good documentation can be as simple as a bullet list of functions with one-liner descriptions. If the UI can't be intuitive, at least you can make the documentation intuitive.
=Smidge=

Online reading habits different?

[Anonymous Coward]

One thing I've noticed over the time i've spent surfing is that most online content has to get straight to the point with as little fuss as possible. If an article can't capture the interest of the reader within the title, or follow up within the first few sentences, people often quit reading and move on. I actually wonder how many people RTFA in slashdot.

Very different from books, where the author is more able to exert without much fear of whiplash...

Re:use XML

[Anonymous Coward]

>provides re-use of content

oh yeah? can you explain how?

Documentation professionals are creative

[HWheel]

I think that a lot of this information is aimed at documentation professionals (technical writers, content strategists, knowledge management system workers, there are a lot of titles) who are very creative and love to work with these systems, rather than analyst/developers who view documentation as an evil waste of time.

From personal experience, I know that it's not that difficult to mark text as "internal use only" so the developers can quickly find the names and values of parameters and "end user only" so that users who actually use the compiled system can see what the different options are.

I think that the issue is less of "creativity" than it is of thinking through the issues and handling them consistently.

Kudos

[jeepliberty]

Between small business environments and downsizing, engineers are now put in a position that requires them to document their software as well as providing operational and installation documentation.

I remember providing input to a tech writer, then red-lining the first draft to the point that rewriting the entire document seemed necessary. While I would rather write PHP or scripts, there is no one who better understands code than its author.

Today's on line documentation provides a variety of methods for an engineer to provide documentation. Such examples are:

How to's and Mini How To's

FAQ

Web page with screen shots

Forums and Blogs

That being said, I am reminded of a conversation with Clyde, a retired avid sailor, who talked about stories in "SAIL" magazine. "First person stories written by sailors usually suck!" he said. "Give me an article written by a professional writer. They're easier to read."

It's easier to write documentation than to try to tell someone what to write. ....Now if only I can break away from coding long enough to read this document on creating documentation.

Re:246 pages is not big?

[Kingpin]

I've been told on multiple occasions that US authors get paid by weight rather than content. Anyone want to confirm or reject this?

I'm sick and tired of having concentrate in order to locate "the point" within masses of text. K & Ritchies ANSI C book sets a fine standard for concise technical books. A fine example for Java is "Java Precisely", http://www.dina.dk/~sestoft/javaprecisely/

Yeah, who needs documentation?

[fm6]

I take it you write your own user docs. Have you considered the possibility that you're not very good at it? Do you know how explain complicated features in a simple manor? Do you have the patience to discuss nit-picky details that you know intuitively but about which your users are totally clueless? Do you know how to organize an immense body of facts so that the reader doesn't go crazy trying to find one small unimportant fact -- unimportant to you, but essential to the user?

Too many engineers look at tech writers as clueless English majors, useful only for cleaning up spelling and grammar. Or arrogant, burned-out former programmers who think they know everything, and really know very little. True, there are a lot of tech writers like that, and their product is not worth reading -- assuming anybody can read it. But there are also serious, motivated tech writers who know a lot about communicating technical subjects.

I like to think I'm one of those. I'm biased of course, but I have been told, more than once, that nobody understood how a product or technology really worked until I sorted a huge pile of random facts into a useful form. (This is especially nice to hear when it comes from the people who designed the system in the first place!) I'm probably not the best in my field, but I think I earn my pay. (Well, no pay right now, industry slump y'know. Oh well.)

Of course, not all documentation really needs a tech writer. You sound like you mostly write little end-user apps. For those, I agree, a good GUI is more important than a good manual.

But consider my own specialty, the API manual. How many of those have you seen that don't make you scream with frustration? Writing good API docs is hard. (Lotta fun though, at least for a compulsive nit-picker like me.)

And writing isn't as hard as maintaining. My last job involved a development framework with more than 10,000 APIs. Which was maintained in RTF. (Please don't laugh, it's not funny.) And which had to be single sourced for four different product targets. (Windows and Linux, two different programming languages.) And, oh yeah, my boss thought that version control was a silly idea.

Why was this documentation base such a mess? Because at this company, the "nobody reads the docs" mentality prevailed. Even the writing team was infected with it. And this self-fulfilling cynicism really hurt the product. The API has a reputation for being obscure and hard to use. Whereas it's really pretty elegant, and even easy to understand, if properly explained. In this case, bad documentation is doing a lot to consign a superior product to undeserved oblivion.

I should end with that pithy comment, but I have to drag the discussion back ontopic. Because of the company's indifference to doc issues, they're only now converting the documents from RTF to markup, something they should have done 10 years ago. Alas, the project is headed up by an intelligent but technologically clueless individual who thinks a little XML transform experience makes him an expert on content management. (Sour grapes? I guess. Then again, I did recommend hiring the guy.) Last I heard, the project was months behind schedule, and was close to being in deathmarch mode.

So I'm deeply interested reading Ament's book. Maybe it'll be useful on my next job. But even if it's well-written, I don't think I'll enjoy the read. Too many lost opportunities.

XML, yes, NBD, no

[fm6]

Yeah, XML is da bomb. I wouldn't use any other format to maintain a non-trival document base. Especially one where single-sourcing is important. But "no big deal"? Guess again.

• There are no affordable off-the-shelf content managment for most technical documentation apps. Yes, there's a lot of content management software out there, but it's either specialized in some other area (mainly web applications, 'cause there's a lot of money to be made there) or it's a general-purpose CMS platform that takes a lot of work to adapt to a particular purpose.

  XML-specific databases are very intriquing. Many have impressive feature sets. But it's still a work in progress. There's nothing out there you can buy and use without spending a lot of time adapting it to your specific project. Even without license fees (usually pretty high) the up-front costs are huge. Try getting your boss to approve spending a lot of bucks on a product with no track record!

• There are lots of XML editing products out there, but few of them are serious products. Some dweeb combines a Java editor component with an XML parsing engine, and behold! A collaborative documentation tool! Not that easy.

  A few solid products are beginning to appear, but they all have serious limitations. I'm really taken with XMetal, but it only runs on Windows. (Even if you're not an open source zealot, you have to be cautious about a product that won't run on the platform your engineers use. Anyway, XMetal now belongs to Corel, which is busy imploding.) XMLSpy is powerful and cross-platform, but its editign features are clunky. FrameMaker 7 is OK (assuming you don't totally hate FrameMaker's primitive GUI), but creating or modifying an XML application for it is a nightmare. And there's really nothing else.

• Retraining writers to think in XML terms is a bitch.

• XML production tools are still pretty immature. XSL-FO will probably stabilize soon, but I wouldn't rely on it yet.

Eventually, XML will take over. But it's gonna be a long, painful transition.

You stick to coding and let me handle the docs...

[Silverhammer]

Blockquoth the poster:

I remember providing input to a tech writer, then red-lining the first draft to the point that rewriting the entire document seemed necessary. While I would rather write PHP or scripts, there is no one who better understands code than its author.

You're right -- but it takes a LOT more than that to produce clean, usable documentation. And yes, I speak from experience; I've been a technical communicator for more than eight years, and I've spent the last two years just cleaning up existing documentation written by programmers.

The problem I've found is that programmers tend to write documentation the same way they write code: they see a project as an assemblage of individual features and widgets, and they put most of their effort towards ensuring each of those features works correctly. The fundamental concepts that tie the features together into an application are largely taken for granted.

As such, the documentation these programmers produce is technically complete and accurate but almost completely nonsensical from a real-world user's point of view. There's no unified flow or top-level view. The user is basically expected to already know what they want to do, so that all they need to do is look up how to do it.

That's why I don't trust these efforts to make documentation "modular." It's impossible to develop a coherent narrative in such a format, and you can't really educate the user without that narrative.