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

Advice for Single-Sourcing

I have seen the future and it works. We have just finished our first single-sourcing project using mif2go to convert FrameMaker source files to HTML Help *.chm files. These files are also the source of our printed user guide AND a hyperlinked PDF of the user guide placed on the distribution CD. There was considerable once-off pain setting up conversion templates (including CSS files) and conversion options but our next project will be much faster. The converted files DO NOT require ANY hand tweaking -- we just hand over to the release people to put the *.chm file on the installer CD. Our testing and support people are rapt, and consider the new help far better than the old help. An outsider would have no inkling that the help was produced in this way.

Finger, Hedley. InFrame (2002). Articles>Content Management>Single Sourcing

A Case Study in Modular Documentation  

Modular documentation is a variation on single-sourcing methodology developed by Interim Technology Consulting in response to a client’s needs. Our client needed documentation on multiple formats that could be easily modified for multiple customers of their customized software package. The process of developing the modular methodology required considerations such as how to define, structure, and access the information modules in a way that worked for the current project and also provided a foundation for future projects. Interim Technology also wanted a methodology we could use for other clients.

Johnson, Melanie M. STC Proceedings (2000). Articles>Content Management>Single Sourcing

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

Cherryleaf Survey: Use of Single-Sourcing Solutions

During March and April 2003, Cherryleaf carried out an online survey into the current trends in technical communication. One of the questions we asked was: Do the people directly involved with user assistance development at your organization use a single sourcing authoring solution? Our findings are summarised in the article

Cherryleaf (2003). Articles>Content Management>Single Sourcing>Reports

Choosing the Right CMS Authoring Tools

There is no single best authoring environment provided by a content management system. Instead, the authoring tools must be matched to the job at hand to ensure they are easy and efficient to use.

Robertson, James. Step Two (2003). Articles>Content Management>Single Sourcing

The Cigarette Papers: Issues in Publishing Materials in Multiple Formats

This paper will describe the products resulting from the Brown and Williamson document collection - two Internet products, one hardcover book, a series of journal articles, and one compact disc (CD) - and comment on associated issues in electronic publications.

Butter, Karen, Robin Chandler, and John Kunze. DLib Magazine (1996). Articles>Publishing>Single Sourcing

Collaborating with Tools for Single-Sourcing  

A discussion of single-sourcing using FrameMaker and WebWorks Publisher.

Bhatia, Neeraj and Frederick Menezes. STC India (2001). Articles>Content Management>Single Sourcing>Adobe FrameMaker

Communicate Editorial Changes

Streamline your review process with the robust collaboration tool set in Adobe® InCopy™ 2.0. With InCopy, you can track changed text, and add notes and comments without disturbing line breaks. Later, others on the team can easily identify who.

Adobe (2003). Articles>Content Management>Single Sourcing>Adobe GoLive

Content vs. Product: The Effects of Single Sourcing on the Teaching of Technical Communication    

Identifies and discusses the effects of single sourcing on the writing process. Provides suggestions for incorporating the teaching of single sourcing into technical communication courses

Eble, Michelle F. Technical Communication Online (2003). Articles>Content Management>Single Sourcing>Rhetoric

The Convergence of Technical Communication and Information Architecture: Managing Single-Source Objects for Contemporary Media    

Single sourcing, XML, and other forms of multimedia have changed technical communicators' work processes and on-the-job duties. Beyond the requirements for traditional skills in writing, editing, and designing, technical communicators must now play enhanced roles within professional environments including organizing, creating, and managing information. To help simplify the complex tasks of creating multimedia documents, in this article we examine the impact that new technologies have had on the technical communication profession. Referring to a wide variety of sources about the fundamental changes to our profession, we synthesize information regarding managing multimedia documents. Although in this article we focus on object management, with an emphasis on the tasks, skills, and tools required of authors of such documents, in future articles we will address object creation and object presentation.

Mott, Richard K. and Julie Dyke Ford. Technical Communication Online (2007). Articles>Information Design>Single Sourcing

Converting from Paper to Online  

This demonstration describes the process and pitfalls encountered during the conversion of paper documents to online, CD-ROM documents that occurred at Cisco Systems, Inc.

Altemus, Desiree L. STC Proceedings (1994). Articles>Content Management>Single Sourcing

Creating Single-Sourced Information Products  

Until recently, single sourcing has been limited to the process of putting identical information into multiple information products. However, the results of a singlesourced approach need not be identical. You can customize the outputs to contain only the information that is appropriate for the specific situation. This presentation provides a high-level overview to the advantages of single sourcing and how to implement and maintain such a solution.

Stevens, Dawn M. STC Proceedings (1999). Articles>Content Management>Single Sourcing

Curing Publishing Woes with a Content Management System  

Mescan's article helps technical communication managers determine which content management solutions are best for their particular goals and problems.

Mescan, Suzanne. Intercom (2004). Articles>Content Management>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

Definition of Information Management Terms

There is considerable confusion in the marketplace regarding the definition of various information management terms. The scope and role of specific information systems is particularly blurry, in part caused by the lack of consensus between vendors. With the aim of lessening this confusion, this briefing provides an at-a-glance definition of terms for a range of information systems.

Robertson, James. Step Two. Articles>Content Management>Single Sourcing>Glossary

Developing a Content-Management Strategy: Implications in a Multi-Language Environment  

Why we went to a single-source CMS and how we went about it.

Douma, Barbara. ComTech Services (2001). Articles>Content Management>Single Sourcing>Case Studies

Developing a Database Publishing System: A Demonstration  

We developed a database publishing system that uses raw data from a database and produces camera ready copy using Microsoft Access, FrameMaker, and Brio Publish. This type of project requires a project plan that defines the scope of the project, a complete understanding of the various relationships in the database, selection of the right tools for the task, and a sensitivity to the needs of the users who face dramatic change in their environment. This demonstration focuses on all aspects of this effort.

Cantoni, Georgina C. and Judith L. 'Judy' Glick-Smith. STC Proceedings (1995). Articles>Content Management>Single Sourcing>Microsoft Access

Developing and Maintaining a Large Document for Publication in Multiple Media  

This paper outlines the development of the Software Technology Reference Guide—a 500-page directory of software technologies— from the planning phase to its publication in both hard copy and HTML. It explores the problems of coordinating multiple, remotely located authors; producing frequent drafts when material is changing rapidly; managing a large documentation project; maintaining a source document for publication in multiple media; and handling the conversion of a complex hard-copy document to a usable online document.

Brune, Kimberly. STC Proceedings (1998). Articles>Content Management>Single Sourcing

Developing Information for Multiple Formats: You Can Get There from Here  

This paper describes the experiences of SAS Institute Inc. in developing single-source software documentation for presentation in multiple formats. The project is an ongoing team effort from all areas of the Publications Division. Our main goal is to develop online and hardcopy reference documentation. Toward this end, we set goals of using single-source files, reusing information, and tracking all information chunks and the relationships among them. To accomplish these goals we had to make decisions about the tools we are going to use, what information we are going to include, how we will design and present the modular information, linking and indexing strategies, and testing. This paper discusses the choices we made in light of our goals.

Moell, Patricia G. and Helen F. Weeks. STC Proceedings (1996). Articles>Content Management>Single Sourcing

Device Indepenence: Single Sourcing's Other Side  

Considers the possible ramifications for technical communicators of device-independent publishing.

Perlin, Neil E. Intercom (2005). Articles>Content Management>Single Sourcing

Distributed Workgroups Employing Single-Sourcing Techniques Around the Globe  

Single sourcing, which is increasingly used at the technical writer's workplace, has now reached the classroom of Technical Communication programs. This paper examines the impact of working on an XML-based single-sourcing solution on a geographically diverse graduate student team whose partners were all singlesourcing novices. It shows that managing communication within the virtual team is superordinate to managing the publication process. The paper discusses best-practice strategies for transient start-up publication teams, which rely solely on online communication, pointing to the differences between teams in the classroom and in business organizations.

Kaempf, Charlotte. STC Proceedings (2003). Articles>Content Management>Single Sourcing

Does Being Technical Matter? XML, Single Source, and Technical Communication    

XML is a recent Web design language that will enable technical communicators to produce documentation that can reuse information and present it across multiple types of media for diverse audiences. However, little is understood about how XML will impact technical communication in terms of theory, academic research, and pedagogy. In this article, I argue that XML requires more interdisciplinary approaches toward the teaching and research of technical communication, particularly with respect to the integration of technical and rhetorical knowledge.

Sapienza, Filipp. Journal of Technical Writing and Communication (2002). Articles>Technology>Single Sourcing>XML

Dynamic Content Management  

Introduces dynamic content, a method of single sourcing that 'meets individual users' needs by assembling a series of information objects in response to the userís requests or requirements.' She walks readers through a mock project involving the creation and delivery of dynamic content.

Rockley, Ann. Intercom (2001). Articles>Content Management>Single Sourcing

E-Learning, Single Sourcing and SCORM  

E-learning is a highly effective way of providing training to widely dispersed audiences. Single sourcing (information reuse) provides the facility to create and store reusable content from a single source, and delivers that content to multi-channel information products for learners. SCORM is the Sharable Content Object Reference Model; it’s an initiative of the ADL (Advanced Distributed Learning Network). This session provides an understanding of how you can create effective e-learning materials using single sourcing or SCORM.

Rockley, Ann and Steve Manning. STC Proceedings (2002). Articles>Education>Single Sourcing>Online