Single sourcing and modular documentation techniques


10-03-2003

Companies communicate with their customers for a variety of reasons using a variety of media.

A full range of documents for a product will typically include brochures, leaflets, specifications, user guides, training manuals, online help pages, and web content. Very often there is a great deal of common content between these but companies divide the responsibility for each across their organization, causing duplication of effort, omission and error. This is where single sourcing can be an important technique for managing your publications effectively.



Single Sourcing and Modular Documentation TechniquesSo, what is single sourcing? A common definition is: (1) Produce a document for paper in Microsoft Word or Adobe FrameMaker. (2) Convert it using, for example, Adobe Acrobat for PDF output or an HTML translation tool such as WebWorks Publisher for online output. This definition treats the Word or FrameMaker file as the single source. This is partly correct but it is far from the whole story.



Single sourcing involves every aspect of the way documents are written and structured. Single sourcing requires you to think about how to write content that works for different target media, paper or online, and different target audiences.



Central to single sourcing is the way you structure content into logical blocks, or modules, and how you assemble modules into complete documents that address different needs. It requires that you identify the different of types of primary modules (such as itemised lists, topics and procedures) and secondary modules (such as tables, figures and examples).



Each primary module must convey a complete idea. The reasoning for this stems from the fact that technical documents are seldom read from cover to cover. Readers find topics of interest by using the index and table of contents, or by flicking through the pages. It is important to use extensive cross-references and visual cues to aid your readers, and to consider how these convert when you use a translation tool.



Effective communications and team-working are important requirements for successful single sourcing. The team must include the authors, marketing communicators, engineers, architects and editors that are involved in developing and marketing your product. Module reuse requires careful management and team-working to avoid information being omitted or repeated.



When modules are reused, they must still make sense. This requires careful use of language. Here, a company style guide and language standards can help to bring your documentation up to the standards of the major US corporations and so enhance the image of your company. If your organisation trades with US companies, carefully crafted documents can form a very effective part of your product offering, and if you are writing for readers for whom English is a second language, language guidelines are a must.



The opportunities for implementing a true single sourcing strategy are improved for smaller organisations by the emergence of XML and by publications software, such as Adobe FrameMaker, which provide powerful and cost effective tools for document assembly, validation and repurposing. FrameMaker can be used to create conditional documents so that different versions for different media can be maintained as a single source for your project.



The book, 'Single sourcing: Modular Documentation Techniques' by Kurt Ament (Publisher: William Andrew Publishing, ISBN: 0-8155-1491-3, price: 28.00) describes these techniques in some detail.



David Spicer is an independent Technical Author specialising in bringing professional technical writing to SMEs and startups in the technology sector in East Anglia. Contact David on david.spicer@wellreadcat.co.uk.

To read more information, click here.