+1 408 660-3219 sales@single-sourcing.com

Update: 2016

Since this list was put together, we've published several books about Arbortext that are available on Amazon in print and ePub. The books cover everything about configuring, authoring, styling, publishing, and managing content in Arbortext.

Resources for anyone getting started with a new single-sourcing project

Folks starting single-sourcing projects are faced with insufficient resources. The biggest 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.

I have found that most of the single-sourcing literature is aimed at writers or managers, not implementers.

On my first single-sourcing project, I was hired to design and implement not to manage. I wouldn’t be selling upwards: my director was championing this project throughout the company. Someone else would be doing that. Someone else would be determining ROI and measuring success. Nor was I the project manager, even though I would help determine which tools we eventually choose. What was not aimed at managers was aimed at writers: guidelines for writing and designing modular documentation.

This is something else that 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 is valuable but it wasn’t what I was looking for as an implementer. However, I knew that these books would be essential for training the writers to write and think modularly.

The programming literature is nearly as bad. The XML programming book that 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, the programmer-oriented 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.

I have never found the one book that describes how to put it all together. You make choices—good and bad—along the way that influences the way you implemented particular pieces. You choose a set of tools. You do as much or as little customization as you're comfortable with and as your goals require.

My goal has always been to provide specific examples that can serve spark ideas to solve someone else’s real problems. That is the best any case study can do: Give you an idea about what you can try. Hopefully, all together, these resources will help bring your project into focus.

Books

I have never found the one book that describes how to put it all together. These are the top 5 books, I'd recommend to anyone starting a single-sourcing project. They're a selection of books from both sides of the issue: the writing side and the programming side. Together, they begin to bring any project into focus.

  1. Definitive XSLT and XPath - G. Ken Holman - This is the ultimate XSLT & XPath book.
  2. Definitive XSL-FO - G. Ken Holman - The authority for learning XSL-FO
  3. Developing SGML DTDs: From Text to Model to Markup - Eve Maler & Jeanne El Andaloussi - Although this book is written about SGML, the basics for data modeling are all here and apply to XML projects as much as to SGML projects. This is a great basic data modeling beginner's book.
  4. Single Sourcing: Building Modular Documentation - Kurt Ament - An excellent book for people staring single-sourcing projects. How to plan and implement as well as how to handle the inevitable staff issues.
  5. Practical DITA - Julio Vazquez, SDI Global Solutions - At 80 pages this introduction to DITA is perfect for the beginner to understand DITA topic-based writing and how each topic is best used.
  6. FOSI Tutorials The definitive book on FOSI. People were always looking for FOSI information and it's been nearly impossible to find useful stuff until this became available.

Mailing Lists and News Groups

These resources are good for folks who are getting started on XML or SGML authoring and publishing projects or who are in the middle of one. (There were many more until Yahoo shut down their Groups.)

  1. comp.text.xml The Extensible Markup Language (XML).
  2. dita-users This group supports users of DITA.
  3. XSL Mailing List The open forum for the discussion of XSL -- Extensible Stylesheet Language.

Other Online Resources

  1. Docbook.org This is the official home page for all things Docbook.
  2. DITA 1.1 Reference When you want to examine a particular DITA element or attribute easily, without slogging through the spec.
  3. Top 5 Resources for Arbortext Users A complete list of the best resources for Arbortext users available.

Note: When you purchase something after clicking links in our articles, we may earn a small commission. Read our affiliate link policy for more details.

Key Concepts:

best practices

Filed under:

Blog