Skip to main content

Content Reuse and Single-Sourcing in Microsoft Word: The Tomia Case Study

At Tomia, we produced all our raw content in Microsoft Word, and provided published documentation in both PDF and HTML formats. Although this was a very common single-sourcing implementation at the time, I would have liked to migrate the raw content to another more flexible source platform. However, there was no option to migrate to any other platform due to company policy. This documentation solution was not a great fit for our user guides because:

  • There was a high percentage of content reuse across more than fifteen different products.
  • content variations for each specific product had to be taken into account before publishing.

While not technically impossible, managing this in Word is a huge undertaking, and Word is not the most stable documentation publishing platform. This led me to search for a tool that could emulate a single-sourcing workflow in Word. In such a system, the foundational mechanics used to maximize content reuse and manage variations are snippets and conditions.

Core Definitions​

  • Snippet (sometimes called a partial, reuse topic, or conref): A discrete, reusable block of content stored in a single source file and referenced across multiple documentation pages.
  • Condition (often referred to as conditional text or conditional filtering): A mechanism used to show or hide specific content based on the target audience, product variant, deployment model, or output format.

Discovering a Solution​

On a visit to a conference in Jerusalem in 2010, I attended a presentation of SmartDocs, a product by 36Software I had not previously heard about.

SmartDocs is an add-in for Microsoft Word that enables you to:

  1. Reuse snippets across your documentation guides.
  2. Set up variables and conditions that you can employ inside or outside of snippets.

Implementation Challenges​

In setting up this system, we faced several challenges.

Content Granularity​

The primary challenge was deciding the granularity of the snippets. We did not want to have to aggregate too many snippets when creating new documentation, as this might make maintenance difficult in the future.

The Outcome: After some trial-and-error runs, we realized that it was better to have larger snippets, in some cases complete chapters, even if that meant they included many conditions.

Content Variations​

The second challenge was managing the content variations. We had to decide how to structure the conditions and variables to ensure that the correct content was displayed for each product variant. This required careful planning and organization to avoid confusion and ensure that the documentation was accurate and consistent. Conditions were set up to filter content based on the product variant, and variables were used to manage common information that needed to be updated across multiple snippets. Each condition was represented by a color applied to the content and named for the product variant it represented. This made it easier to identify and manage the variations within the snippets. However, there were several limitations:

  • The conditions were not hierarchical, which meant that we had to be careful when applying them to ensure that the correct content was displayed.
  • The palette of seven colors was not large enough to cover all of our products, and if two or more colors were applied to the same content, it displayed as purple. This meant that you could not immediately see which conditions were applied to the content.
  • Several of the available colors were quite dark and made it difficult to read the content when they were applied. This was a significant issue, as it impacted the readability of the documentation in edit mode, which is where the writers spent most of their time.

We had to implement a system for naming the conditions and using the color palette strategically to manage these limitations. For example, we used lighter colors for conditions applied to products with the most specific content and reserved darker colors for conditions applied to products with less specific content. We also implemented a naming system that made it clear which product variant each condition represented, which helped reduce confusion.

We asked 36 Software to expand the color palette with lighter hues, and make it hierarchical, and they implemented these features in a later version of SmartDocs. This was a significant improvement because it made it easier to manage content variations and improved the readability of the documentation in edit mode.

We did not encounter any negative issues with the variables feature.

Linking Word Files​

Although Word has a Master Document feature that allows you to link multiple Word files together as in a book, we found that it was not a stable solution for our documentation needs. The Master Document feature can be prone to corruption and can cause issues with formatting and content management. As a result, we decided to avoid using this feature and instead focused on making sure that we could apply snippets across the files with bookmarks and references to those bookmarks with complete integrity. To overcome Word's rebuilding numerical reference codes every time a snippet is referenced from one file to another, or even within the same file, we needed to ensure that any bookmarks were explicitly named throughout the files, and that the same name was used in the snippet and in the referencing content. This allowed us to maintain the integrity of the references and avoid issues with broken links or corrupted files.

Version Control​

Once you already have a library of snippets, you can build a document by adding any snippets from your library to a new document in a SmartBuilder. When you need to create a new version of the documentation, you can create new snippets based on the previous version's snippets, and rename them for the new version. You can then build the document for the new version with the updated snippets. This allows you to maintain a clear history of changes and ensures that you can easily revert to previous versions if needed.

Publishing a Document​

Publishing a document with SmartDocs is a straightforward process. Once you have created your document with the snippets and conditions, you can use the SmartDocs Snapshot feature to generate the final output for conversion to PDF or HTML format. Snapshots use a combination of reusable variables and conditional text to automatically generate multiple document variations, ensuring that the correct content is included in the final output based on the target audience and product variant. For output to PDF, SmartDocs uses the built-in Word PDF export feature, which allows you to generate a high-quality PDF document directly from Word. For output to HTML, we exported to WebWorks for well-structured HTML code based on the content and formatting of the Word document. WebWorks is a SmartDocs technology partner, and the integration between the two products allows for a seamless workflow from Word to HTML.

Maintenance​

Updating to a new SmartDocs version was normally not an issue. However, company-driven Microsoft Updates and Service Packs did cause downtime over the years due to incompatibility with the SmartDocs version. We required SmartDocs support to resolve these issues.

Summary​

Overall, while there were challenges in implementing the single-sourcing system in Microsoft Word using SmartDocs, we were able to overcome them through careful planning and organization. Using snippets and conditions allowed us to maximize content reuse and manage variations effectively, which ultimately improved the efficiency and consistency of our documentation process. We were able to maintain documentation for, at its high point, a product line with 12 flavors of products. This was an elegant solution to the needs of the department and company.