A Democratic Approach to Overcoming DITA and CMS Issues

Home/Publications/Best Practices Newsletter/2009 – Best Practices Newsletter/A Democratic Approach to Overcoming DITA and CMS Issues


February 2009

A Democratic Approach to Overcoming DITA and
CMS Issues

CIDMIconNewsletter Sarah-Beth Doner, Research In Motion

Migrating a documentation set to a DITA Content Management System is a monumental task. Judging from the presentations staged at various content management conferences, it seems that organizations undertaking this feat are mindful of the logistics. IT representatives take special care to evaluate the growing number of software options when choosing the CMS and XML authoring tools for their writers. Management carefully weighs costs versus benefits and calculates the return on investment.

Converting content seems to be a hit and miss affair. More often than not, organizations underestimate the time and cost required to analyze and convert content into DITA-compliant topics, and timelines slip as a result. Despite these setbacks, conversion is accomplished. The nuts and bolts of conversion to DITA involve careful planning, collaboration among various stakeholders, and determination on the part of everyone involved. While these accomplishments are laudable, there is often one question that begs to be asked: What about me?

The move to a DITA content management system has a significant impact on the lives of the people in the trenches. Writers, editors, and tools specialists are presented with a new toolset and a new way of writing, reviewing, and managing content. Adjusting to this new approach to technical communication can be a jarring experience. Ensuring buy-in from these frontline stakeholders is just as important as staying on-budget and establishing a stable toolset.

During our ongoing rollout of a DITA CMS at Research In Motion (RIM), we invoke a democratic approach to achieve buy-in from the writers, editors, and tools specialists who interact with the system on a daily basis. By engaging frontline stakeholders in decisions around tools, processes, and training, we have achieved a relatively smooth transition. By sharing our experiences, we hope to inspire a similarly democratic approach in organizations implementing their own content management solutions.

The Steering Committee

The Software Documentation department engaged in a rigorous vendor-selection process. A team of stakeholders compiled an exhaustive list of requirements: diverse content needs, increasing localization demands, technical specifications, and budgetary considerations were described in detail. This careful vendor selection process evolved into a pilot project to examine the performance of the selected CMS under real-world conditions. The pilot encompassed the conversion of one set of deliverables for a BlackBerry device release. From that pilot came the first opportunity for a democratic intervention: the Steering Committee.

The Steering Committee was comprised of all participants in the CMS pilot project: editors, writers from the end user documentation team who were performing the content conversion, tools specialists rolling out the CMS and related publishing tools, plus occasional participation from management at key decision points. Other writers from the end user team who weren’t participating in the conversion but were interested in the project also participated in the Steering Committee. The committee met on a weekly basis, and participants were expected to bring forth issues they had encountered during the previous week. Issues included content analysis concerns such as how to handle prerequisite information or whether to create a new conditional text attribute. Bugs or enhancements to the toolset were brought forth, including improvements to map building tools and publishing format concerns. The content-development process was discussed when an apparent bottleneck in the editing cycle occurred or when a new approach to reviewing XML markup was needed.

This democratic committee was driven by consensus-based decision-making. When an issue was brought to the table, it was described in thorough detail to ensure that the context and impact of the issue was apparent. Possible resolutions were put forth by all participants with consideration for the downstream affect of the decisions. Having a wide cross-section of participants allowed for thorough consideration of the impact from all angles: tools, writing style, process, and ease of maintenance.

In addition to laying the groundwork for the evolution of our content management solution, this committee functioned as a support network for all participants in the pilot. Our migration to a DITA CMS involved a steep learning curve. Participating in weekly meetings to share experiences and work through issues allowed for a sense of stability and optimism during the pilot. It also provided a formal context for knowledge transfer. In short, it allowed all involved to learn from the experiences of their fellow participants.

In hindsight, this committee could have been more effective if writers from all teams were able to participate. However, their participation did not seem practical at the time because the writers were not yet involved in the conversion process and therefore did not have insight into the concepts and issues involved in the conversion. As a result, all decisions were made with the needs of our end-user documentation team in mind but without a clear understanding of the impact these decisions would have on the other writing teams. Some early process and tool decisions were later discovered that did not adequately meet the needs of the other writing teams and had to be revised.

Guidelines, Style, and Tools Committee

The Guidelines, Style, and Tools committee (GST) was formed after the CMS was approved and moved into production. This committee consists of a tools specialist and all of the editors in the Software Documentation department. This group continues to meet on a weekly basis to make decisions regarding editing procedures, style guidelines, and related tools.

The GST was originally formed to solidify editing process changes that coincided with the implementation of the CMS. During content analysis, editors worked alongside writers to define rules for rewriting content for conversion to DITA. The GST was tasked with codifying those rules through the company style guide and a set of authoring guidelines. The style guide dealt with traditional issues around word usage and trademark conventions. The authoring guidelines were developed to narrow the DITA specification into a preferred subset of DITA elements and provide examples of their preferred use. These conventions were further formalized through the development of a set of DITA topic templates that provide the base set of DITA elements for specific content types, such as troubleshooting or architecture content. Tools were later developed to allow writers to easily create new topics based on the templates. These templates have been so effective that we have chosen not to develop specialized topic types.

Just as with the Steering Committee, the GST draws from the insight of a broad cross-section of participants. This committee relies on the editors to act as delegates for the writing teams. Each editor works closely with one group of writers and is expected to advocate for the specific content and process requirements of that group. Thus, the editors and the tools specialist can make decisions while remaining confident that the needs of all the writing teams are being represented.

Committee for PCMS Stabilization

After the pilot was complete and the chosen CMS was moved into production, the Steering Committee was retired. Decisions regarding tools and processes were primarily handled through direct discussion between writers and tools specialists. The result was a less than ideal and distinctly non-democratic method for addressing CMS issues. Since there was no longer an official forum for communicating concerns, issues were primarily raised by a small group of the most vocal writers in the department. It soon became clear that the issues being addressed were not necessarily the most critical concerns of the department as a whole. Even within this subset of issues, it became difficult to assess priority and allocate the resources to implement a resolution. Due to this inadequate method for addressing issues, writers started to feel that the CMS was not a stable toolset and did not meet the needs of writers; this perception was especially acute in the teams that did not participate in the pilot and the related Steering Committee. Thus, the Committee for Publications Content Management System Stabilization (CPS) was born.

The CPS consists of all of the tools specialists in the department and at least one representative from the editing team and each writing team. This committee meets weekly. Participants are expected to bring concerns raised by their teams during the previous week; they are also expected to convey information from the CPS to their respective teams. As the name suggests, the initial role of the CPS was to ensure the stability of the toolset; this goal was achieved by identifying and troubleshooting high-priority issues. In all cases, issues were prioritized according to the consensus of all CPS participants. This prioritization helped the tools specialists to make informed decisions when allocating resources to resolve issues. In many cases, once an issue was identified, it could be resolved through process improvements, internal tools development, or formal training. If an issue could not be resolved internally, the tools specialists engaged the CMS vendor to provide technical support and tool enhancements to fulfill the needs identified by the CPS.

In all cases, issues were prioritized according to a consensus of all CPS participants. This method helped the tools specialists make informed decisions when allocating resources to resolve issues. In addition, the committee also served as a forum for tools specialists to provide detailed explanations when an issue could not be resolved. In some cases, perceived bugs were actually desired behaviors, due to permission settings or process restrictions. Communicating the underlying reasons for these behaviors was often sufficient to dispel negative perceptions.

Only a few months after its inception, the CPS could be credited with improving the overall perception of the stability of the CMS. Thus, the focus of the group naturally shifted away from troubleshooting and toward offering enhancement ideas. Members of the CPS offer suggestions to increase the efficiency of writers and editors working in the system. All enhancement suggestions are prioritized according to a consensus of CPS participants. Many of these suggestions are presented to the CMS vendor as formal Requests for Enhancements. Other enhancement suggestions are acted upon through internal development of custom tools or formal process improvements.

Perhaps the greatest benefit of the CPS is the sense of ownership it instills in all participants. The committee provides a forum to foster communication and allow for direct input into the direction the CMS takes so that it can evolve to meet the needs of all writers and editors. It also ensures that development proceeds according to the priorities of the entire department.

Training & Mentoring workgroup

The democratic approach to resolving CMS and DITA issues has carried over to other initiatives within the Software Documentation department. The Training & Mentoring workgroup was established to address the perception that new-hire training was inconsistent and insufficient. This committee shares a similar structure with the CPS: representatives from each team within the department meet on a regular basis to provide suggestions and prioritize initiatives related to training and mentoring.

To address their original mandate, the group created training sessions and produced a set of mentoring guidelines to support an initial new-hire training program. Significant attention was paid to formalizing CMS-related training to offset the steep learning curve of the toolset and related processes. The training program continues to evolve, including a recent focus on refresher training and career development initiatives for the more experienced employees in the department.

The Training & Mentoring workgroup gathers suggestions and gauges the success of its initiatives through a set of surveys issued to training participants. Within two months of completing the new-hire training program, participants are invited to share their perceptions of the program. The surveys ask recent new hires to rate the effectiveness of the timing and the overall execution of the training program; they are also asked to suggest new material to include and material that can be removed from the training program. Workgroup participants review the surveys and establish focus groups to follow up with recent new hires on particular areas of concern.

Similarly, career development initiatives for established employees are currently being developed based on the results of a department-wide survey initiated by the committee. The surveys are an important tool for this democratic committee because they allow all members of the department to make their needs and opinions known. Then, workgroup participants can focus on the most important issues identified in those surveys, enabling immediate action.


The democratic techniques established within the Software Documentation department at RIM have proven effective in easing the transition to a DITA CMS. The various committees encourage open communication, ensure transparent decision-making processes, and instill a sense of responsibility and ownership among all participants. By employing these methods, frontline stakeholders are engaged in the process and the system. When they ask the question, “What about me?” there is a clear and definite answer that isn’t based solely on technical or budgetary concerns.CIDMIconNewsletter

About the Author

Sarah-Beth Doner_bw_cropped

Sarah-Beth Doner
Research In Motion

Sarah-Beth Doner is a Documentation Services Specialist for Research In Motion. She joined the Software Documentation group at RIM early in the implementation of their DITA CMS and took on responsibilities as a system administrator and tools specialist. She also provides training and documentation to support users of the CMS. Sarah-Beth graduated from the University of Waterloo with a degree in English Rhetoric & Professional Writing and a Digital Arts Communication Specialization.