Single Sourcing

Building Modular Documentation

246 pages
November 2002
William Andrew Publishing
ISBN-10: 0-8155-1491-3
ISBN-13: 978-0-8155-1491-6

Single sourcing is a method for developing information that can be re-used in different formats for different audiences and purposes. Although project planning and document conversion are essential to any single sourcing project, it is modular writing that ultimately determines success.

This book explains in plain language and by example how to build modular documentation. It includes a conceptual overview of the single sourcing method, a 10-step process for transforming linear documents into modular documents,and detailed guidelines that explain how to structure content, configure language, and leverage technology to maximize usability and re-usability.

Review in Technical Communication

The following book review by Jacelin W. Colosky appeared in the August 2003 (Vol. 50, No. 3) issue of Technical Communication: Journal of the Society for Technical Communication.

Book Review
by Jacelin W. Colosky

Single Sourcing: Building Modular Documentation. Kurt Ament. 2003. Norwich, NY: William Andrew Publishing. [ISBN 0-8155-1491-3. 230 pages, including index. $39.00 USD (softcover).]

Single sourcing is a buzzword in the technical communication industry as technical communicators try to take it from great concept to current trend. Kurt Ament’s Single sourcing: Building modular documentation is one of the first books written about single sourcing; previous discussion on the topic has been mainly in the form of articles or seminars. Unlike most of those articles, Ament’s book does not center on theory but provides a useful, practical approach to single sourcing, with clear, easy-to-follow examples.

In the Foreword, Ament establishes his credibility by sharing information on the major single-sourcing projects he has been a part of, including a range of project sizes in a variety of industries. He also establishes the basis for his view and understanding of how single sourcing works, such as his belief that “single sourcing is a methodology, not a technology” (p. x). He then briefly touches on the requirements and value of single sourcing.

The Preface provides useful information about the book. For example, Ament provides a high-level overview on how the information in the book is organized, including a blurb on each chapter; a mention of the glossary, index, and cross-references; and alphabetized guidelines. He identifies his audience as technical writers, editors, managers, and students. He maintains that there is value in reading the book for every practitioner because “Even if you are not involved in single sourcing, this guide provides you with guidelines to improve the usability of your documentation” (p. xiv). His goal is to help technical writers achieve immediate success as well as continued success with their single-sourcing projects.

Ament defines single sourcing and positions its use in practice. Chapter 1 addresses theory: what single sourcing is, reasons for doing it, and how it works. Unlike all-inclusive definitions found in many other sources, his is simple and broad. He puts his specifics not into the definition, but into the discussion of how to single source.

He establishes the value of single sourcing to both writers and readers. Ament also discusses how to ensure success for a single-sourcing project. For example, he says:

Although its primary goal is to save time and money, single sourcing improves the quality of your documentation. By requiring you to develop modular information that is usable in any format, single sourcing makes document usability an all-or-nothing issue. If your content is modular, your single-sourcing project succeeds. If not, it fails. To succeed you have no choice but to incorporate usability guidelines into your documentation standards. (p. 3)

He then breaks the components down into smaller chunks and explains for each what works and what doesn’t. For example, his definition of single sourcing includes reusing information, and the definition of reusable content follows. In that definition, he differentiates between content-based documentation and format-based documentation. This definition is followed by an explanation of why format-based content is not reusable, but content-based content is reusable. The information shared in these explanations is broken down even further. Because his information is modular and presented in small sections, it is easy to skim through to find what you’re looking for, making the book useful to a wider audience.

One thing I find most refreshing in Ament’s contribution to the single-sourcing conversation is that he does not stop at theory. After establishing the need for modular writing, he explains what modular writing is and why it works, and then provides steps to establish, build, and link modules. Ament says, “Modular writing is a cognitive process. You evaluate content, break it into the smallest possible modules, label the modules by content type, configure the modules into meaningful hierarchies, and link the hierarchies into related hierarchies” (p. 23). He goes on to say, “If you develop modular content that makes sense in any context, you can re-use it in different formats for different audiences and purposes” (p. 47).

For readers ready to start implementing their single-sourcing projects, the meat of the book begins after the foundation in theory has been established. Chapter 2 takes you through 10 steps for creating modular documents:

• Identifying modules

• Labeling modules

• Organizing modules

• Building modules

• Editing modules

• Organizing documents

• Cross-referencing documents

• Converting documents

• Testing documents

• Developing guidelines

Each step is broken down into considerable detail and is cross-referenced to guidelines and examples. This is an effective way to combine the different components of a single-souring initiative that have been identified by the professional community. The guidelines and examples are specific enough that you can get a tangible understanding of the process, while also being generic enough that you can easily adapt them to your specific situation. For example, the guidelines for captions include rules for “Wording figure titles,” which are different when writing from the system perspective versus from the user’s perspective. Chapter 2 could serve as a procedure for those beginning a single-sourcing initiative.

Subsequent chapters provide detailed instruction on how to structure content for modular writing and how to configure language to increase re-usability of your documents. Ament says, “If you write in active voice, second person, and present tense, you speak directly to your users. Likewise, if you use parallel construction in headings, captions, list items, and so on, you make it easier for users to scan documents for the information they need” (p. 149). The next section then breaks down those topics.

Ament provides a table of contents at the beginning of each chapter. Additionally, there is a cross-reference, tip, or note at the bottom of almost every page, alerting you to related information. Ament calls these pieces “cognitive bridges” for connecting modules. The structure of the book is very consistent and was obviously laid out as a guide, because it repeats pertinent information in each section. This can be slightly distracting if you read the book sequentially. However, this is not much of a problem if you use the book mainly as a reference.

The last chapter, which covers leveraging technology to automate parts of your single-sourcing process, includes such topics as localization, conventions, conditional text, and development tools. This section is also cross-referenced where appropriate earlier in the book.

Overall, Ament’s tone is conversational, peer-to-peer, and consistent. Even when discussing theory, he remains firmly grounded in reality. For example, he advises, “When you first implement single sourcing, set modest goals for small but live projects with real deliverables and real deadlines. Small projects keep you safe, small steps keep you sane, and live projects keep you honest” (p. 20).

I appreciate Ament’s use of both good and bad examples. The book has informative summaries, logical organization, and good navigation tools, including a glossary and an index. All of these navigational tools are needed, because the chapters are long. Ament helpfully keeps reminding you that each project is different and that you should modify the guidelines and steps to fit your own corporate and project requirements. I also appreciate his addressing how single sourcing benefits the reader; most literature on the topic discusses just benefits for the writer and his or her organization.

As a small-business owner, I’m pleased to see a lack of emphasis on tools. Although Ament does discuss the available tools and their benefits, that section is at the back of the book. He discusses tools as they enhance the single-sourcing effort rather than allowing them to dictate it.

Ament’s book is well written and thought-out, and at only 230 pages, it’s a quick read. The detailed, specific approach makes it a useful guide and reference book as well as a textbook in a graduate-level course or a corporate environment. As a practitioner, I’ve been following the movement toward single sourcing for several years. I have been waiting for a reference that is detailed enough to be truly useful. I believe Ament’s Single sourcing: Building modular documentation is the best such resource so far.

JACELIN W. COLOSKY is a technical writer, editor, and partner at Silicon Hills Documentation Services. She belongs to STC’s Austin chapter and is a master’s student at Texas Tech. Her experience in high tech, government, construction, and journalism ranges from lone writer generalist to publications team specialist.

Review in The Rockley Bulletin

The following book review by Ann Rockley appeared in the February 2003 issue of the The Rockley Bulletin.

Required Reading
by Ann Rockley

“Single Sourcing: Building Modular Documentation”
by Kurt Ament
Publisher: William Andrew Publishing (December 2002)
ISBN: 0815514913

The concept of modular content is central to single sourcing, but until now there was very little information available on how to actually design and create effective modular documentation. Now Kurt Ament has created the book that helps you do just that.

“Single Sourcing: Building Modular Documentation” provides a clear and concise introduction to building modular documentation. The book is divided into five parts.

Chapter 1 “About single sourcing” introduces the concepts of single sourcing including the reasons, benefits, types, and what makes single sourcing successful.

Chapter 2 “Building documents” gets right into the heart of the subject by providing a 10 step process for building modular documentation including how to identify, label, organize, build, and edit modules then build documents from your modules. He also emphasizes the importance of developing guidelines for authors to follow.

Chapter 3 “Structuring content” provides guidelines on creating structured content. Guidelines are provided for such common content types as procedures, glossaries, examples, indexes, notes, and troubleshooting scenarios, and many more.

Chapter 4, “Configuring Language” emphasizes that good modular content is more than just “chunks” of information; it is well written content. This chapter provides guidelines for developing consistent standards for writing content such as abbreviations, capitalization, punctuation, tense, and voice.

Chapter 5, “Leveraging technology” provides an introduction to how you can use technology to support your single sourcing effort.

What I like best about “Single Sourcing: Building Modular Documentation” is that Ament practices what he preaches; the content is highly modular, consistently structured, and full of examples. He provides examples of common content and how the content could be changed to reflect the concepts he presents. The book is an easy read and is chock full of tips and guidelines.

“Single Sourcing: Building Modular Documentation” provides an excellent resource for creators of single source technical documentation.

ANN ROCKLEY is President of The Rockley Group, Inc, a consultancy that assists organizations in developing enterprise content management and unified content strategies. Rockley is a frequent contributor to trade and industry publications and a featured speaker at numerous conferences in North America and Europe. Rockley is an Associate Fellow of the Society for Technical Communication and has a Master of Information Science from the University of Toronto, where she teaches Enterprise Content Management. She is a member of the Board of Advisors for The Content Management Systems Evaluation Lab (CMS Evaluation Lab) at the University of Washington Information School (Executive Director, Bob Boiko). Rockley is the author of Managing Enterprise Content: A Unified Content Strategy with TRG Senior Consultants Pamela Kostur and Steve Manning, New Riders Publishing ISBN 0-7357-1306-5, Oct. 2002 She can be reached at 905-415-1885 or rockley@rockley.com, www.rockley.com.

Review in STC Single Sourcing SIG Newsletter

The following book review by Scott Abel appeared in the March 2003 issue of the Society for Technical Communication Single Sourcing SIG Newsletter.

Finally, a recipe for building modular documentation!
by Scott Abel

“Single Sourcing: Building Modular Documentation”
by Kurt Ament
Paperback: 246 pages
Publisher: William Andrew Publishing (December 2002)
ISBN: 0815514913

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. 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!.

SCOTT ABEL, the Vice President of the STC Hoosier Chapter, is a consultant at Nims Associates, Inc. who helps clients determine the strategies for their content management implementations.

Review in E-STREAMS

This review by James A. Buczynski appeared in the May 2003 (Vol. 6, No. 5) issue of E-STREAMS, an online newsletter for technical librarians from Yankee Book Peddler (YBP) Library Services.

Subjects: Technical Writing
by James A. Buczynski

Single Sourcing: Building Modular Documentation, by Kurt Ament. Norwich, NY, William Andrew Publishing, 2003. 230p., index. ISBN 0-8155-1491-3 [ GOBI GOBI 2 ]. $39.00. LC Call no.: T11.A39 2003.

Every now and then, you come across a book that makes you stop and think. This is one such book. The timing of the release of Single Sourcing could not be better, for it draws together many of the ideas being presented today at online content development, web publishing and online learning conferences. There is a consensus building that early online web-based learning systems generally failed to satisfy their objectives due to bad information design and a lack of adherence to accepted pedagogical principles. This book masterfully addresses the information design part of the problem. Although aimed at technical documentation writers, editors, professors and students, the methodology is being adopted by non-technical educators involved in developing online learning content. “Single sourcing is a method for developing re-usable information.” The methodology delivers “modular content that works anywhere, anytime, anyhow.” Information that by design can be both migrated to other communication mediums and cognitively repurposed to address specific audiences or learning objectives. The book presents an overview of the single source technical documentation development method used by large defense, software and multimedia companies.

The book is a well-executed example of modular documentation. Even before reading the content of the book, the efficiency of single sourcing is evident by just browsing through the pages. Concepts being presented are easily identified, defined and connected to related concepts. Each chapter in the book begins with an introduction followed by an annotated table of contents for the chapter. The ten steps of the single source methodology to building documents are laid out in the second chapter of the book. The third chapter, the largest of the book, covers layout guidelines for structuring content. Lastly, writing guidelines are presented in chapter four. Rules for using abbreviations, sentence construction, punctuation, and other “language configurations” are covered. The last chapter of the book, “leveraging technology” is the weakest part of the work. The chapter almost seems like an afterthought as it lacks the depth of treatment the other areas of the book receive. The chapter presents technology considerations requiring attention in writing guidelines for content development. Overall, the book is strongly recommended for professionals involved in developing online information and corporate and academic library collections supporting technical communication and e-learning development activities.

© 2003 YBP Library Services, Inc. All rights reserved.

JAMES A. BUCZYNSKI is an Information Services Librarian at Seneca@York Learning Commons.