Documentation and Courseware Working Together



April 2009

Documentation and Courseware Working Together

CIDMIconNewsletter Laura Readdy, Siemens PLM Software

Writers, editors, and managers at Siemens PLM Software have long recognized the common content between training courses and documentation. We have often asked ourselves how we can get the most out of our rich content suite while providing a solid knowledge base for our customers.

As we learned more about XML-based authoring, information modeling, and content management, a solution path emerged. Content sharing has become a key concept. Achieving direct reuse of a topic across two or more deliverables without change is now the objective. The notions of shared topics and collaborative content development have become fundamental building blocks for integrating our two content domains: documentation and courseware.

Cost containment in development, localization, and maintenance is an important part of our overall justification for a content management system (CMS) and process changes. Important as it is, the internal return on investment is not at the heart of our motivations. Delivering quality content that customers need to be successful with our software products is the greater goal.

“Whether learning new skills or referencing information on the job, users need real-world user tasks backed up by relevant concepts. Once trained, they can find the same information on the job as they studied in the training, and plenty of supporting content to go with it. The integration of teams, processes, and source content—from initial audience and task analyses to final deployment—is a guiding principle that will result in improved content quality and customer satisfaction.


In establishing our vision, we reinforced the commonality between courseware and documentation by defining common objectives and targeting consistent messages to our audience. Customers and quality took center stage as we focused on task-based topics, minimalism, structured writing, and progressive disclosure methods. Customer engagements and reuse measurements are critical to our efforts. The goals are to increase our productivity and time to market while controlling localization costs. We want to achieve 40 percent reuse within the next 3 years.

The timeline to achieve our vision started in 2002 by moving to XML-based content authoring (see Figure 1).

Readdy_Figure 1

Figure 1: Timeline for setting the stage

Since that time, we have added an information architect role, topic-based information modeling, the CMS, a content designer role, and an organizational change that enables our documentation and courseware writers to work closer together.

This article focuses on one Siemens PLM team of documentation and courseware writers who work together on shared content. Combined, this team is responsible for about 100 documentation guides, 12 instructor-led courses, and a growing number of self-paced training modules. So far, we have shared content between a subset of our documentation deliverables and 25 percent of our course materials. Though we started this project before our CMS, the CMS implementation has allowed us to accelerate topic reuse.

Organization and teams

How did we go about getting documentation and courseware working more closely together?

We wanted to create content teams focused on sharing topics. Initially, we had two separate organizations for documentation and courseware that reported to our director. We needed to change our organization to better support our shared content development, so we placed these organizations under one manager responsible for all documentation and courseware deliverables.

This structure allowed us to set goals for content integration and send a strong message to managers and writers about our business objectives. To help with the transition, we added a new position of Subject Matter Expert/Content Designer to help define and start the process. We had already created an Information Architect position, and many of the structural guidelines were in place. This information model supports both our documentation and courseware writers. The Information Architect continues to help guide and direct this new team (see Figure 2).

Readdy_Figure 2

Figure 2: Documentation and courseware organization

Documentation and courseware managers are working together to develop a common authoring process, and writers are developing common content. We still produce the same deliverables for our customers, but now we are leveraging the strengths of all our content experts to enrich the content.

Content structure

Our strategy for content structure is supported by the CMS which stores our core content source files—concepts, processes, and reference topics—in one content structure (see Figure 3). This library now has 14,000 topics. Documentation contains the superset of content. We apply user profiles and task analysis to help drive the content development to be more task-based rather than feature-based.

Readdy_Figure 3

Figure 3: Content source mapping

Courseware uses a subset of the documentation content, but also provides its own unique core content topics. Courseware also includes additional training components like activities, databases, and assessments that are not needed in the documentation. Underlying this, courseware uses the same user profiles and task analysis as documentation to help support a consistent message and terminology for our customers.

Ultimately, we need to provide documentation and courseware deliverables for our customers. These include our standard documentation guides, self-paced training, and instructor-led training materials.

One high-level process

The first major step was the transition to an overall content plan for both documentation and courseware. The respective managers worked together to develop, improve, and communicate this plan to the new organization. One of our biggest challenges in coordinating this process has been the shear volume of documentation and courseware content. Existing “legacy” topics must be re-authored to be shareable.

The collaborative activities in each key area of the development process are shown in
Figure 4.

Readdy_Figure 4

Figure 4: Collaborative activities between documentation and courseware writers

Development process details

Let’s explore the details of our shared content development process. We have a pressing question: how do we transform existing documentation and courseware content so that it can be used as shared content?

Management sponsored a special initiative to bring together the right mix of people to develop a prototype of this process. Participants included a documentation writer, courseware writer, content designer, subject matter expert, information architect, and editor.

This team developed the process outlined in Figure 5 for merging existing documentation and courseware content.

Readdy_Figure 5

Figure 5: Shared content development process

  1. Identify common content by mapping courseware and documentation topics.
  2. Merge existing content by analyzing mapped topics and designing shared topics.
  3. Update topics by creating shared topics. Share the update responsibility between the documentation and courseware writers.
  4. Review shared topics with developers, writers, editors, and instructors.

As we merge existing topics, we ask ourselves three important questions:

  1. What changes are needed to share topics?
  2. Have we missed any topics that can be shared?
  3. Can existing shared or copied topics be improved?

The topic design must support all our deliverable types: documentation, student guides, instructor presentations, and online self-paced training.

Answers can include these changes: One or more of these changes are typically needed to derive content that can be shared with courseware:

  • Restructuring of content
  • Bulleted lists of items
  • Minimalism
  • Break up long topics into shorter, one page topics
  • Graphics
  • Tables of information
  • Short, concise sentences

Results of reworked content

In 2008, we reworked approximately 426 topics and have realized a topic reuse rate of 66 % between these documentation and courseware topics. This number does not take into account courseware topics like objectives, activities, and summary topics, but all content-based topics that have a potential to have content overlap. Beyond documentation and courseware topic sharing, we have additional sharing between documentation deliverables and between courses.


The CMS was required to support the process of authoring shared content. We chose XyEnterprise’s Contenta for our XML content. Contenta manages all of our documentation and courseware content in the same datastore using the same content organization. This allows us to package topics into maps and to reuse topics easily.

Challenges and solutions

With any new initiative come challenges. Let’s review four key challenges and how we addressed them.


Lessons learned

We learned many lessons along this cultural and technical transformation and we continue to learn. Executive support requires ongoing quality improvements and ROI measurements. Our documentation and course writers are still learning to work together to develop content. We strive to keep our customer focus and drive our content to be task-focused, rather than preoccupied with features and functions.

Developing shared content is difficult and requires an ongoing commitment from management and the teams. It is best done with a common process across teams. We are still working to fully integrate our teams.

The investment in a CMS and a common content hierarchy has been key to having a foundation for content sharing. Training, writing guidelines, and mentoring are ongoing to support writers with the required tools and methods.

Technical leaders within the teams are needed to help with this transformation. Our information architect and content designer helped the teams to see that the vision could be achieved. Key writers have also been instrumental to push the shared content forward. We have leadership from the top, but the new process must be driven from inside the organization.

Our effort to get documentation and courseware working together to share content has been well worth the investment. The incremental funding and resources needed to transform existing content and authoring teams should pay off in the future. We expect that shared topics will be more cost-effective to maintain. Most importantly, our customers will soon reap the benefits of improved content across all our deliverables.CIDMIconNewsletter

Contributing author: Steve Fowler, Siemens PLM Software

About the Author

Laura Readdy_bw

Laura Readdy
Siemens PLM Software

Laura Readdy is a Senior Courseware Developer for the Learning Media Development division of Siemens PLM Software. Laura has 25 years experience in the information technology area and specializes in technical courseware design and delivery. Her current focus at Siemens PLM Software is the integration of courseware and online help for the product lifecycle management (PLM) market. She has been able to use her experience working with customers to apply a task-driven approach to information development. Laura has a BS Mathematics/Computer Science from Gonzaga University, Spokane, WA.