Home/Publications/Best Practices Newsletter/2012 – Best Practices Newsletter/Structuring Technical Publications and Instructional Materials to Maximize Reuse


August 2012

Structuring Technical Publications and Instructional Materials to Maximize Reuse

CIDMIconNewsletterDawn Stevens, Comtech Services, Inc.

One of the most compelling business case arguments for the move to DITA, structured authoring, and reusable content is the significant cost savings realized in translation budgets. Organizations have realized savings of hundreds of thousands of dollars by only having to pay for shared content to be translated once. With the Learning and Training specialization opening the door for shared content between technical publications and instructional materials, the potential for similar cost savings now exists in the development of this content.

However, your ability to share content between technical publications and instructional materials is tied closely to how you view your relationship, as shown in Figure 1.


Figure 1: Relationship Between Technical Publications and Instructional Materials

Each of these viewpoints is a barrier to content reuse. The first two situations result in power struggles as one group tries to take control of the other’s materials, while the last keeps everyone in silos—free from power struggles, but also ignorant of the reuse potential.

Although the third viewpoint might result in 100 percent reuse, the model ignores that there are valid, significant, and necessary differences between the two domains:

  • The use of technical publications is optional, while instructional content is frequently required by management or regulations.
  • Access to technical publications is random; users are in and out as needed. Access to instructional content is typically sequential, following a prescribed path.
  • Technical publications are consumed in small, single pieces of information at a time. Instructional content is expected to be viewed altogether in one session.
  • Access to technical publications is user-driven, while access to instructional content is scripted or guided by the designer or trainer.
  • Technical publications tend to be referential, used as often as needed. Instructional content is frequently expected to be internalized so that no further reference to information is required.

Sharing content does not mean that these differences need to be ignored. The differences likely indicate that you’re not going to find reuse opportunities at a macro, or deliverable level. Each group will have its own maps and bookmaps to create its own deliverables. Each will have some unique content specific to its purpose and the deliverables it creates. But this doesn’t mean that sharing cannot happen at a deeper, micro-level.

The first step in maximizing reuse between the organizations is to recognize that content sharing is not an all or nothing venture. We need to view the organizations as equal and overlapping, as shown in Figure 2.


Figure 2: Content Sharing

By accepting the differences and not struggling to wipe them out, we can move immediately to a cooperative discovery of common content and plan that content appropriately. The challenge then is in maximizing the amount of overlap.

Find the Common Ground

Before you can determine the appropriate structure of shared content, you obviously need to determine what content can be shared. As part of your business case for working together, perform a content analysis on your current technical publications and instructional content.

  • Determine the percentage of content that is unique to each group and that will likely never be shared. This content will probably include preface and introductory material, objectives, assessments, and instructor notes.
  • Determine the percentage of content that is virtually the same—content that could become identical after being edited following a common style guide and information model.
  • Carefully look at information that is similar, but presented differently. Determine why the content is different—is it a stylistic or personal choice? Does it relate to the different purposes of the deliverables? Ask whether or not the content could be the same. Could you assign conditions to the necessary differences to take advantage of the similarities?

During your analysis, remember that you are not concerned about the location of the content within the deliverables. At the macro level, the shared content may have entirely different contexts. For example, suppose you are working with content about a digital SLR camera. Content about setting shutter speed might be found in a user guide within the context of the specific dial on the camera that allows you to set it. That same content in a tutorial, however, might be within the context of a lesson on low-light photography.

Expect that you will need to create and use conditional content within shared topics. From the onset, create conditions for technical publication and instructional content, as well as for instructor and student audiences within the instructional content. It’s important to recognize that much of the inherent differences in content can be easily isolated and conditionalized. For example, in presenting task information, technical communicators typically provide generic step-by-step content. They don’t know the specific situation that the users will be in when performing these steps or the specific data users will be working with. In contrast, these same steps in instructional content are presented within a context, a specific scenario that defines the exact information that should be provided in each step. Consider, for example, these steps for setting the shutter speed on a digital SLR camera (Figure 3).


At first glance this content appears different and not shareable; the instructional content is just too specific to be used within the technical publication, while the technical publication is not detailed enough to satisfy the needs of the tutorial. However, with a little compromise on structure and the use of conditional text, we can share the basic step content (Figure 4).


In fact, we can even add an instructor note to the topic (Figure 5).


From one topic structured in this way, we can produce content for a user guide, tutorial, and instructor guide. Whether this content appears in a chapter about the modes of the camera or a lesson about low-light photography, the information is appropriate and useful.

Leverage what Each Group Does Best

With your common content identified, you may still ask who should be in charge of that common content. Who will write and own the content, and what involvement will the other group have in that creation? Ideally, you can take advantage of what each group does best.

For example, consider dividing content creation responsibilities by information type. Common complaints about technical publications center around the amount of unnecessary background information that gets in the way of completing tasks. Conceptual material is long-winded and difficult to get through. Instructional materials may not suffer from this problem because instructional designers are trained to focus solely on meeting the identified objectives, providing no content that will get in the way of what needs to be learned. They tend to push back on SMEs who provide detailed background information to get to the heart of what is really necessary to support the learner. For this reason, you might consider asking your instructional designers to create the conceptual information that supports the user tasks, while your technical writers take charge of task and reference content.

Drilling further into the content, you might also consider assigning specific DITA elements exclusively to each group to help limit the number of conditions in a topic. Instead, these elements could be left out of stylesheets where the content doesn’t apply. For example, you might assign <tutorialinfo> for instructional designer use only. In the previous shutter speed example, the specific selections to make on each step would be coded as <tutorialinfo> and would not be rendered in the user guide stylesheet.

Similarly, specific elements might be assigned exclusively to a group to leverage their specific skills or even to balance workload. For example, because technical publications are designed for in and out, rapid access, you might put the technical writers in charge of all elements relating to search strategies, such as the <prolog> sections of all topics, especially <indexterms> and <keywords>, and the <shortdesc> elements of all topics.

In these approaches, where specific groups are using elements exclusively, clearly both groups will touch the same topic during development. Be sure that you have clearly defined your workflow and established checks and balances. How will each group ensure the integrity of the information they have created as well as influence the content that they are sharing? You clearly cannot have uncontrolled and random editing of shared content and must work to establish trust between both parties.

Plan for Reuse

Even with reuse strategies in place, sharing content will not happen unless you plan for it. Each group must be aware of what the other is doing and what content is available for reuse. Assignments must be made to ensure you are not duplicating effort. Expect to overhaul your entire project planning process to maximize your reuse potential. You must start each project with a collaborative planning stage during which the groups

  • list all topics that are needed for all deliverables in each discipline
  • identify the topics that can be shared
  • indicate where conditional text is expected that will result in both groups needing to touch the topic
  • establish the owners of each topic and the order in which each owner will touch the topic. For example, you might have technical writers create the first draft task topics and then have instructional designers add tutorial information and examples.
  • set due dates for topics based on the overall deliverable due dates. For example conceptual information written by the instructional designers and required for technical publications will be due well before it is needed for tutorials or other instructional content.

Consider adopting an annotated topic list, such as the one in Figure 6, to address these easily.


From this topic list, each group can distribute its workload and create individual deliverable maps.

Form a Cooperative Governance System

It should go without saying that these reuse strategies rely on the teams agreeing on certain underlying standards and processes. Before attempting to share content across disciplines, establish a governance board consisting of representatives from each group and agree on:

  • style guide and writing standards. Your instructional designers and writers must approach content with the same voice and tone, agree on word choice and terminology, title topics in the same manner, and so on.
  • information architecture and model. Topics must conform to specific structures so that the same type of information appears consistently in the same sections within the topics.
  • development processes. Establish how the teams will engage and interact with SMEs, what process will be followed when reviewing content, what will happen when reused topics need updating, and so on.
  • communication strategies. Build trust by ensuring that the teams invite each other to status meetings, copy each other on project emails, and ask for help or advice on challenges. Plan to hold joint wrap-up meetings to discuss how to improve the work next time.

Certainly, planning for and setting up such a cooperative venture is not easy, but the reuse potential between these related disciplines more than justifies the effort. CIDMIconNewsletter


Dawn Stevens

Comtech Services, Inc.


Dawn Stevens is a Senior Consultant specializing in information development, instructional design, and management consulting. With over 20 years of experience, including 10 years at Comtech, Dawn has practical experience in virtually every role within a documentation and training department, including project management, instructional design, writing, editing, and multimedia programming. With both engineering and technical communication degrees, Dawn combines a solid technical foundation with strong writing and design skills to identify and remove the challenges her clients face in producing usable, technical information and training. Dawn has a keen interest in metrics, editorial and design standards, user and task analysis, and single sourcing strategies. She enjoys helping our clients gain efficiencies through improved publication processes, minimalist writing techniques, and designing for reusability, with an emphasis on XML and DITA solutions.