Guest Post: Justifying Single Sourcing, a Case StudyOctober 8, 2013 at technical communication
The following is a guest post by Swapnil Ogale, a technical writer based in Australia.
Working as a Contractor – Technical Writer across various industries, I have used a number of techniques to create a wide range of documentation, such as Online Help, FAQs, User Guides, Process Flows, Troubleshooting guides.
I was interviewed (by the organisation I currently work for) with a specific task of creating developer documentation for a data warehouse project. One of the first things I discovered once I started working here was that they have never had a Technical Writer in the organisation before, so anything I plan/recommend would mean the starting point for any such conversation in the future. During the first few weeks of research and scoping the documentation needs, I realised the content had the potential of being used and re-used across various other avenues.
I had some prior experience working with Single Sourcing; and hence had no hesitation in recommending a Single Sourcing strategy to work with this content.
In this case study:
- I use the word “content” for a collection of text, screens, diagrams, videos, and other relevant pieces of information.
- I do not cover all aspects of single-sourcing; instead just explore the key criteria that helped me recommend this strategy.
What is Single Sourcing?
Single-sourcing refers to the concept of creating content once, but reusing this content across various outputs/media.
This concept may not mean a great deal for the user, but for the writer, it is productivity defined. Writers often have to create different pieces of documentation, adapting to the client requirements and user needs. In doing so, many a times the writer is often accessing the same content, but modifying this to fit the client needs. Many a tools in the market, currently, take this concept a level higher by allowing the writer to keep all their content in a single place, but empowering them to use and reuse this content across different outputs.
Create once, publish many times
As discussed above, the very concept of single sourcing revolves around creating content once. This base content can take any form, but XML is being increasingly used these days, given its powerful advantage of separating content from the presentation in any document. Using XML based help authoring tools, you can easily use the same content for an online help, as for a printed manual. You can even reuse parts of, or the whole content for a mobile output. You need to plan the content carefully so that these content chunks can be reused to publish them to different outputs. Once the writer has created this content, it is then a matter of publishing this content across multiple outputs.
How was it relevant to my project?
Once I had a fair idea of the number and types of documents that could potentially be created in the future, I opted for a help authoring tool that I had used before and was comfortable with – Madcap Flare. I could have just as easily picked up any other help authoring tool such as Adobe RoboHelp, or AuthorIT. The idea was to use an application that would allow me to create content in one place, but also give me a flexibility to publish in different formats.
Once you embark on the single-sourcing journey, you often realise the apparent benefits of this concept. Not only does it make it easier for you to create and store all content in one place, you can also review content for its relevance. This leads to a more efficient approach to creating content, thereby reducing errors and redundancy in the documentation.
For example, in my case, I found out that some of the content I collated from the developers could be useful for the other staff equally. That prompted me to take a different approach in creating these particular documents. Much as I kept the style similar to my other documents, I also ensured the language for these documents stays as simple as possible for the non-developer staff to read. Flare helped me create and use conditional text (more on this below) to customise the same page, so that it appears differently to different users.
Single sourcing allows you to build on the concept of “create once, publish many times”, by introducing concepts such as conditional text (called differently by different help authoring tools) and variables. You may be familiar with conditional formatting in Microsoft products, especially MS Excel, where cell contents/rows/columns may behave differently in some cases, depending on a specified condition. This behaviour is controlled by conditional formatting. Similarly, in help authoring tools, you can mark or flag parts of, the entire text or entire documents/images as conditional. This content is displayed, hidden or behaves separately, based on the pre-defined condition.
With single sourcing, you will also find that you end using and changing a large number of repetitive elements, such as company names, product names etc. In such cases, you can include this information in a variable. Variables allow you to change a particular element across the entire content dynamically. You can achieve the same result with a global find-and-replace, but including a variable makes this very efficient, and error-free.
How did I apply this to my project?
I organise all my content based on a rough table of contents I drew up at the start of the project, as part of the Information Plan. While it is not required to use the same structure necessarily, I can easily use conditional text to flag relevant topics and/or content wherever they are located in the file/folder structure. Based on how the user wants to view the content, I could organise the content using the conditions/flags I have assigned to the content.
While I was working on the developer guide, my Manager asked me to assist another team in the organisation with their help documentation. I could have easily created another project for that team; instead, I included all their content in the same project as the developer guide. I just had to include the relevant variables, as applicable to the other team’s documentation throughout the content. Once I completed documenting their user guide, I could reuse some of the content from my developer guide and publish to a completely separate format from the same project in the help authoring tool.
Single sourcing allows you to reuse images across multiple outputs. Help authoring tools have features built in that permits you to specify image properties such that they appear relevant to that medium. If you are outputting to an online medium, you can specify how you want the image to display. Similarly, if you are using the image in a printed format, you can specify how you want the image to be included (mostly high-quality, but smallest size as possible). You can also use external tools such as SnagIT to edit/annotate screenshots and other diagrams (process flows etc). Most of the help authoring tools also have some sort of an image capture and processing feature built in, which allows you to integrate these images directly into your content.
Once you have created the content, the next important element of single-sourcing is to be able to reuse the content to be published across a range of outputs and formats. Most of the help authoring tools will allow you to publish your content to formats such as Word, HTML or PDF. You can publish your content to a printed output, to an online help, embedded within specific software or to a mobile device output. Help authoring tools will also assist with automatically deploying outputs to relevant locations. For example, online help to a website, printed outputs to printing or a shared location.
How did I include this in my project?
A lot of developers I work with are technologically savvy, so they don’t mind looking at images in the documentation and clicking on relevant sections of the image to read about more technical information on that topic. As a result, I include a lot of clickable images that links to relevant content in the output. Most of my images also have properties set so that they display and print differently based on the output format.
All of my content is published online, to a shared location or document repositories within a content management system. On the odd occasion, a user may request for a printed copy of the developer guide, and I can just as easily publish the content in a printed format.
The single sourcing strategy has been justified for the following reasons:
- Avoids issues with duplication of content. All of my content resides in one location, reducing inconsistencies.
- Sets a consistent look and feel across all of my documentation projects.
- Can publish to different audiences with different information requirements.
- Allows me to adapt quickly to changing requirements or ad-hoc requests.
- Complete control over content as well as output format and design.
Swapnil Ogale says “My name is Swapnil Ogale and I have been Technical Writing for the better part of the last 8 years in Australia. I became a Technical Writer with the sole intention of satisfying my passion for writing and curiosity to learn new things. I discovered how simple, clean, and effective documentation assists others with doing their jobs efficiently.”