Customer Reviews

William Andrew Publishing Technical Writing Series: Single Sourcing: Building Modular Documentation

5 star:		(7)
4 star:		(1)
3 star:		(0)
2 star:		(2)
1 star:		(2)

 

 

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

The entire approach given in this book is consistent enough with Information Mapping® that it can serve as a guide to learning that highly effective technique on your own.

I was trained in Information Mapping® in 2000 and have used the principles to excellent advantage since then. More importantly, those techniques - called 'single sourcing' in this book - foster the ability to create coherent documentation using geographically distributed teams. This is because the single sourcing technique described in this book is concerned with document design, which is based on a process that identifies requirements and bases the initial draft on procedures and knowledge instead of the more common approach of writing an ad hoc outline.

At the heart of the author's single sourcing approach is a concept called 'chunking' - grouping information into manageable chunks - and factors such as relevance and consistency. When these are employed the cost-effectiveness of the method becomes apparent for two reasons:

(1) Documents written by teams are consistent and developed using a set process.
(2) Components within the documents - blocks - can be reused in other documents because they will address a specific, relevant topic (a chunk).

What I like about this book is the fact that it makes Information Mapping® available to anyone who will take the time to read this book and apply the principles. I also like way it offers an off-the-shelf solution to any company that wants to implement a cost-effective, highly efficient documentation standard that supports readable documentation that can be used instead of 'shelfware'.

The best way to learn about this book is to visit the official Information Mapping® site (ASIN B0000B01VZ) upon which many of the principles in this book are based. What you will discover there will give you a reasonable idea about what to expect from the approach in this book. If you are a technical writer who works with software architecture I also recommend that you read "Documenting Software Architectures: Views and Beyond" (ISBN 0201703726) because the approach in that book is consistent with both the "Single Sourcing" approach, as well as Information Mapping®.

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!

I was recently investigating options for single sourcing when I came across Kurt Ament's book Single Sourcing: Building Modular Documentation. Based on the glowing reviews the book received, I decided to order it from Amazon.com.

Unfortunately, the book was not what I expected. For the price of $[...] on Amazon, the book provides little help to experienced professional writers. My biggest complaint is that too many pages of the book are spent promoting the author's own ideas of style and usage rather than discussing true single sourcing issues. (134 out of 210 pages, to be precise, were dedicated to matters of style.) Some of the style and usage guidelines are handy for modular documentation, however, I believe each company should decide its own appropriate guide for style and usage rather than relying on the author's word. Had he couched his preferred guidelines as examples, perhaps I would be less inclined to view them negatively.

Granted, understanding how to simplify and standardize language is key to developing text for reuse within a body of work and reuse text for localization. Writers need to understand how to simplify and standardize text before starting to think about how to leverage tools for single sourcing. Describing how to use standard language, however, is different than promoting a writing style, and probably requires far fewer pages than Ament dedicated to it.

One of the reviews on Amazon raved about how well this book could be applied in conjunction with Information Mapping. I disagree. The author clearly does not approve of breaking processes or procedures into tables, which is a cornerstone of Information Mapping. In fact the author has very strict guidelines about when you should use a table and when you shouldn't. (Again, he is pontificating a particular style rather than offering solid advice on single sourcing.) Don't take my word for it; examine the table of contents very carefully before you buy this book.

What the book does well, is offer good general advice on where to start thinking about chuncking your documentation in order to reuse it again and again. Also, Ament provides a concise lexicon of single sourcing terms that will help you properly articulate your ideas to your teammates. Most of the flags and highlighting I used in the book were confined to chapters 1, 2, and 5.

This book might serve well in an introductory professional writing course, but if your company is seeking guidance on single sourcing, find a book that is tool specific or find a book that sticks to single sourcing and leaves style and usage decisions up to you.

As other reviewers have pointed out, examine this book carefully before you buy it. This book provides excellent basic guidelines on writing technical documentation, and I recommend it strongly to tech doc managers and instructors as something to pass along to their entry level writers and students. Similarly, it might be a helpful resource for engineers or other technical contributors who find themselves having to prepare usable documents for readers outside of their team.

However, if you're an experienced technical writer looking for guidance on how to migrate your existing body of content from multiple authoring sources to a single source application, you need to look elsewhere. This book does not cover migration to or implementation of single source applications. I found Ann Rockley's book, Managing Enterprise Content: A Unified Content Strategy to be a helpful starting point for figuring out how to migrate to single source methods and tools.

Ament's book does not delve into the details of tools implementation. However, writing modular documentation that can be chunked and reused is a necessary prerequisite to single sourcing.

It's a good idea to understand the stylistic and writing requirements before getting into tools. Ament's book should be used in conjunction with tool-specific information.

This book is a style guide, with guidance like, "When introducing small sections that contain subsections, use itemized lists rather than sentences"; "Begin optional steps with a clear visual and verbal indication that they are not mandatory"; and "When listing commands, follow the capitalization rules on which your product is based." The beginning and end of the book provide a shallow discussion of single sourcing, but much of the book is style guidance like this. Maybe I'm missing something, but what does that have to do with single sourcing? I sure don't understand these 5-star reviews and encourage you to flip through the pages of this book before buying so you know what you're getting.

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. --Information Services Librarian

I am starting a project using single sourcing with multiple outputs and this was a good place to begin. The book was obviously written using modular documentation and it was easy to read. I didn't think it was the most exciting or "seductive" book (using Horton's terminology), but it got the job done and used itself as a good example.

A very special book. If you ever manage or write documentation

This book is not a book about grammar. It applies the best ideas in information architecture and information usability that technical writers or commers can use.

If you're using Framemaker, Arbotext, Webworks, Flare, Blaze or even the newer RoboHelp generation of tools where 'single-sourcing' is the 'thing' to be talking about, this book is a must. Its necessary reading. It goes beyond writing and goes into helping you structure for single-sourcing.

You'll probably find new ideas, and applications in developing your doc projects that you can use immediately, simply by the way the book is written and presented. All the earlier and best reviews of this book are pretty head-on.

The guidelines that the book recommends are actually applied to in the development and authoring of the book...this is probably why i think this book is a rather 'special' book. There are lots of books on writing, clear and simply, but this book is the real deal. Short, concise applicable.