The 1-2-3s of Single Sourcing (Was Single Sourcing and Thinking Bigger)

[Gwen Thomas <gthomas -at- PAYSYS -dot- COM>]

<snip>I'd rephrase this and say "Separate structure from formatting and content both". </snip>

With traditional tools, it's possible to start creating content before you decide what the structure of the doc is going to be.  You can add formatting any time along the way.  As a result, it's easy to think about the entire deliverable as one process.

In contrast, whether you're using databases or a tagging system, adopting a single-source, multi-use approach forces you to think about what you're building in terms of a series of separate processes.  The following steps do not include obvious and ongoing steps such as examining your current doc (existing data set, existing deliverables), determining your needs (target data set, target deliverables), developing maintenance and disaster recovery processes, developing skills, setting expectations.  Instead, here's a high-level look at migrating to a single-source approach to documentation:

1. Build a structure (the source) to hold data (content) that will be merged into multiple deliverables.

2. Decide what metadata is required to allow the data to be sorted and filtered and otherwise manipulated as needed.  Adjust the structure to hold the metadata.

3. Populate the structure with content and associated metadata.
a) If necessary, build a user interface to facilitate data input.
b) If necessary, develop processes for migrating large amounts of existing content.  This might include "prep" work to organize the existing content or add metadata prior to the migration.

4. For each deliverable, build a shell (template, master page, mail merge document, etc.) to define:
a) the content to be extracted from the source (using merge fields, controls, or whatever approach is appropriate for the tool being used)
b) 1-up information (headings, introductory information, etc.) to be "wrapped around" content
c) the appearance (formatting)
d) instructions (properties, commands) for pulling content into the shell from the source OR for pushing content out of the source into the shell

5. Perform the push/pull to create a deliverable.
Note:  under the best of circumstances, this deliverable is a single-use, "disposable" document.  Although you could use it as a "template" to be modified when producing a next-generation document, ideally, you would instead update the source and shell for the next generation, and then generate a new document.

6.  Perform any post-generation processes such as:
a) clean-up (hope you don't have any, but sometimes there's no ROI for building a new step to the generation when a simple FAR could do the job)
b) pre-press
c) electronic delivery processes.

Three important notes:
1.  Developing this process can feel more like software development that like document planning.  Some folks aren't going to like how it feels.
2.  Traditional doc planning processes and metrics won't cover all the bases.  I've had better luck using a traditional software development model for engineering the structure, formatting, and development processes.  Doc planning tools have been okay for the content portion of the migration.
3.  Editors either love or hate single-sourcing.  Advantages:  You can present similar kinds of information together for "specialized" edits.  It's possible to focus on content when you know that the shell will not allow formatting errors.  Disadvantages:  Change.  You'll probably want to develop new editing cycles that address content before it goes into the final deliverables.

Gwen Thomas
Knowledge Management Consultant
CIBER Information Services


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=