Structured Authoring for Content Reuse

Problem

Documentation writers would learn of changes to a feature of the product, find that feature in the documentation, and make the change. Then, a few days later, receive a report that the documentation still had the old description of the feature. The writer would dig in on the complaint and realize that the same feature had been described in multiple places in the documentation, and the change they had made originally had only fixed on of the places.

Goals

We wanted to make feature updates fast and predictable to save the documentation team the embarrassment of having the same errors reported over and over again.

Solution

This company obviously needed structured authoring to provide a single, predictable place for every piece of information. However, the culture of this company could not withstand too much overhead. Content needed to be turned around fast, sometimes within hours, and was revised frequently, so we needed something simple and flexible.

We analyzed the content and designed a lightweight, DITA-compatible structure that was enforced mostly by convention rather than by strict tools. It boiled down to four basic chunks:

• A concept called “What Is” where all the definition information lived.
• A concept called “Why Use” where all the benefits of the feature lived.
• A procedure called “How to” where all the step-by-step instructions lived.
• A collection of reference chunks called “Appendix” where definitions of terms, properties, and other reference information lived.

These chunks could be reused across documents. For example, a writer might create the “How to Schedule an Appointment” procedure in a feature guide about the Calendar, but then reuse that procedure in a larger-scope solution guide about Planning a Conference. Since the writers all knew the convention of creating the procedure in the feature guide, they knew to make the changes there if there was a change to the Calendar feature, and the update would automatically cascade through any other places where the content appeared.

Results

Structured authoring has benefits for everyone involved:

• Writers can create and update documents faster and more efficiently because they know exactly where the content lives.
• Reviewers can review more quickly because they know where to expect to find content and can identify immediately if something is missing.
• Users can consume content more easily because they learn the structure and can predict where to look for the particular piece of information they need.