Add One Egg, a Cup of Milk, and Stir: Single Source Documentation for Today

What happens when the software firm you work for decides it will not deliver large printed manuals any more? Then the request comes to put everything online. Six months later, user profiles shift to the World Wide Web and you're asked to deliver HTML. In the future, a database of SGML information chunks may let us deliver anything, any which way. Today, we must devise a system that allows us to 'author once, publish many'. Such as system is crucial for software and hardware documentation. The method I chose was to go from FrameMaker to Acrobat .pdf files to HTML. I wrote in Adobe FrameMaker, then converted to .pdf files with Adobe Acrobat, and converted FrameMaker to HTML files with Quadralay WebWorks Publisher. But while we're waiting for the future, just learning SGML and diving deep into DTDs alone could be a mistake. SGML is a language which sets out structure, and most of us are concerned with content. Enter Information Mapping, or information types of your own devising. Identifying chunks of information such as a procedure for changing the default printer is extremely important. If we then mark each chunk for an index and record its type and title, we've also got the keywords for a future database.

Stieren, Carl. Simware (1997). Articles>Documentation>Single Sourcing>Adobe FrameMaker

Challenges and Advantages of Modular Documentation  

Using a modular process has proven highly effective in developing both on-line and printed documentation. This paper identifies module types and structures, discusses technical, psychological, and management hurdles, and demonstrates how this process can improve consistency and quality. In addition it discusses tools and resources, preliminary planning, preparation of personnel, and (briefly) tracking results.

Greene, Linda L. STC Proceedings (2000). Articles>Documentation>Single Sourcing

Customizing the Appearance of Your Manual, Help System, and HTML Help System  

Doc-To-Help gives Help authors complete control over the look, feel, and content of a project's printed manual, Windows Help system, HTML files, and HTML Help system. Maintaining different content is controlled using Doc-To-Help's conditional text feature, which allows authors to mark content for print-only, online-only, WinHelp-only, and so on. In this article we discuss how you control the appearance of the printed manuals and Help using Word templates, and HTML output using cascading style.

ComponentOne (1999). Articles>Content Management>Single Sourcing>Documentation

Integrating Local and CRI Online Documentation Using SGML and DynaWeb  

This paper tells how Lawrence Livermore National Laboratory enriched CRI's online documentation set by publishing local manuals using the same SGML DTD used by CRI and delivered using (a more sophisticated version of) the same World Wide Web server (DynaWeb 3.0). This approach supports flexible local content and styles, yet integrates local and CRI manuals through one access mechanism and user interface. We explain the basic strategy involved, compare the benefits of this approach with three alternatives, and discuss the problems to which it gives rise.

Girill, T.R. Delft University (1996). Articles>Documentation>Single Sourcing

Managing Documentation: From Hard Copy to Repository  

New technologies have added to the complexity of today’s documentation management. Documents have grown beyondpaper into compoundfonns that can include audio and video segments, and may exist only in electronic form. This documentation can capture much of an organization’s knowledge and wisdom. But often, these intellectual assets are lost because the organization lacks a formal knowledge management system. Many professional communicators already manage their documents from creation through delivery, but stop short of archival. This paper explains how to plan for efficient document production so that intellectual assets become available for easy retrieval and reuse.

Sharp, Michael V. and Beverly M. Bruns. STC Proceedings (1997). Articles>Documentation>Single Sourcing

One-Stop Shopping: Creating a Single Source Information Base for Multipurpose Delivery  

Until recently, many companies developed two sets of documentation for each product - one set was delivered with the product, and the other set was used for customer training. In this panel presentation, we will discuss a new approach used at Lucent Technologies. Lucent is producing task-oriented customer documentation, stored in an asset repository, that can be tailored to each customer’s requirement and that can also be used for training purposes. This new way of producing information involves an integrated effort and provides order and structure to the development of information products. Each panelist will develop a different aspect of this process. how and why of applying order and structure to the process.

McGuire, Mildred E., Lee Anne Center, Gregory Henderson, James Moran and Christine Wentworth. STC Proceedings (1998). Articles>Documentation>Single Sourcing

Single Source Information: An Agile Practice for Effective Documentation

In agile software development you want to travel as light as possible, and the easiest way to do that is to choose the best artifact to record information. I use the term 'artifact' to refer to any model, document, source code, plan, and so on created during a software development project. Furthermore, you want to record information as few times as possible, ideally only once. For example, if you describe a business rule in a use case, then describe it in detail in a business rule specification, then implement it in code, you have three versions of the same business rule to maintain. It would be far better to record the business rule once, ideally as human-readable but implementable code, and then reference it from any other artifact as appropriate.

Ambler, Scott W. Agile Modeling (2006). Articles>Documentation>Single Sourcing>Agile

Single-Source Documentation: Docbook versus DITA

When it comes to documentation projects, primarily technical, medical, and scientific, using XML is a no-brainer. The heavy thinking comes when deciding which flavor of XML to use: DocBook or DITA (Darwin Information Typing Architecture). I have been a steadfast supporter of DocBook for over six years. I'd tried my hand at DITA and gave it up as a fad; lots of bells and whistles, but too complicated to integrate. And couldn't DocBook do everything DITA promised anyway?

Mulvihill, Teresa. LiveTechDocs (2008). Articles>Documentation>Single Sourcing>XML

Single-Sourcing Online Documentation for Multiple GUIs, Languages, and Software Releases  

A small documentation team devised an innovative workflow to provide documentation for Interleaf publishing software for Windows and Motif, in English, French, German, and Japanese, using a single set of online source documentation. We used technology to streamline tasks, maximize communication, and optimize the documentation for future updates.

Bayer, Douglas, Rosalyn Reiser, Andrea Muren Shanahan and Margaret Waters. STC Proceedings (1995). Articles>Documentation>Single Sourcing

A Solution to Writing Winning Sales Proposals and Other Sales Documents

This article explains how we built a solution to producing sales proposals and other sales literature for our own company using an affordable content management solution.

Pratt, Ellis. Cherryleaf (2003). Articles>Business Communication>Single Sourcing>Documentation

Tips and Techniques for Single-sourcing with RoboHelp X5

RoboHelp now offers a rich set of features for delivering multiple customized outputs out of a single project. This article by Matthew Ellison provides some guidelines and tips on using the key single-sourcing features.

Ellison, Matthew. WritersUA (2004). Articles>Documentation>Single Sourcing>Adobe RoboHelp

Pick a Card

There are obvious benefits to single sourcing, the ones that roll off the tongue the minute single source is mentioned: multi-format publishing, consistency of information, quicker updates of common content, lowering translation costs and so on. But beyond all those, what else is there? In this guest blog post, Gordon McLean discusses just that.

McLean, Gordon. DMN Communications (2009). Articles>Content Management>Single Sourcing>Documentation

Preparing Anchored Frame for Conversion in RoboHelp

When FrameMaker content containing Anchored Frame is imported to RoboHelp, the Anchored Frame is converted to corresponding image in generated XHTML content. The quality of generated images has been an area of concern. While some users are satisfied with the quality of images generated, others feel the scope of improvement in the image quality. This blog describes some of the best practices and workflows that will help obtain improved quality of generated images. In other words, it will allow users to maintain the original quality of source images generated through specialized image editing applications.

Adobe (2009). Articles>Documentation>Single Sourcing>Adobe FrameMaker

Single Sourcing Help Content for Software Manuals    

Mohr details a method by which you can single-source content from an online help system to produce a manual for the same software application.

Mohr, Robert P. Intercom (2009). Articles>Single Sourcing>Documentation>Help