Jennifer Krul, Research In Motion Limited

If only content management systems came with “how-to” manuals for content analysis and conversion. When on the brink of a move from an unstructured writing environment to DITA and a CMS, we sure could have used one. So, what’d we do instead? We panicked a little, and then we dove in, learning from our mistakes and working together to develop processes and guidelines.

Keeping our heads up: Surviving the pilot project

For our pilot project, we chose to tackle most of our end-user content. How did we survive the content analysis and conversion of this content? Two key things immediately come to mind: we determined early on what we wanted to accomplish during content analysis, and we worked collaboratively to solve problems and discuss possibilities.

Developing a clear notion of what content analysis meant to us

When we started, we knew that content analysis would be a good opportunity to clean up our content, but we didn’t have a clear idea of what content analysis meant to us. In short order, we developed the following list of content analysis tasks:

    • Identify user goals for all topics.


    • Identify opportunities for reuse.


    • Identify topics that should be removed.


    • Verify that content follows minimalism guidelines.


    • Classify topics as task, concept, or reference (DITA topic types).


    • Classify and organize content units within topics.


    • Determine requirements for attributes.


    • Identify topics that should be split.


    • Rewrite topic titles to reflect user goals.


    • Identify any gaps in content.


  • Improve clarity and consistency.

Collaborating and communicating

Before we started analyzing and converting content, we created a project team (lead writers and a technical editor) and defined roles and expectations for team members. This team met often to review content, discuss design patterns (information models) for topics, and brainstorm possible solutions for problematic content. We recorded content analysis results (for example, topic structure information, DITA tagging information, issues, questions, and so on) for all topics in an analysis spreadsheet. This spreadsheet became a key tool for sharing ideas and communicating information to other writers helping out with revision and conversion work.

Learning to swim: Developing processes, guidelines, and training

In the final stages of the pilot project, we turned our attention to developing processes, guidelines, and tools to help other writers on the team move their existing content into the CMS.

Developing a process for content analysis and conversion

We needed a step-by-step process, a roadmap, that would guide writers as they analyzed and converted their content. We wanted to develop a process that would keep writers involved, providing them with a continued sense of engagement with their content and an opportunity to learn about structured writing and DITA in a hands-on way.

How did we develop this process? Essentially, we analyzed what worked and what didn’t work during the pilot project, and we used this analysis and some additional brainstorming to identify the following list of key tasks for analyzing and converting existing content:

    • audience analysis (information architect)


    • definition of deliverables (information architect)


    • content analysis (writer)


    • review of content analysis (information architect or editor)


    • content revision and conversion (writer or co-op student)


    • planning for new content (writer)


    • review of plans for new content (information architect or editor)


    • development of new content (writer)


    • editing (editor)


  • map development (team lead, lead writer, information architect or editor)

To help writers and editors move through the process, we developed tools to help them plan for and think about content analysis in a useful way. For example, we created a planning sheet to help members of project teams define roles and set expectations for content analysis and conversion work. We also created a DITA analysis spreadsheet template for writers to use as they analyze their content.

Creating authoring guidelines and topic templates

We based our first authoring guidelines on decisions we made during the content analysis and conversion of pilot content. As we move more content into the CMS, our authoring guidelines have evolved. To drive the development of these guidelines, we formed a team (consisting of an information architect and technical editors) that meets weekly to discuss authoring issues that arise during content analysis or editing and to make recommendations for additions or changes to authoring guidelines.

With input from writers and writing team leads, this team has developed file naming conventions for topics, a code review checklist, and several design patterns that reflect our standard topic types (for example, concepts, tasks, troubleshooting topics, process flows, and so on). Our design patterns define the structure of content within topics and provide writing conventions and tagging information for that content (for example, how to phrase and tag prerequisite information, how to phrase and tag task results, and so on). All the design patterns are based on the three main DITA topic types (task, concept, reference). So far, we have not identified a need for specialized DITA topic types.

To make it easier for writers to create content that adheres to our authoring guidelines, we’ve created topic templates (based on our design patterns) that include appropriate tags and provide instructional information for content. When creating topics in the CMS, writers copy these templates and replace the instructional content with their own content.

Future plans for authoring guidelines? Currently, the team is focusing on creating design patterns for deliverables. These design patterns will define what content a specific type of deliverable should include and how that content should be organized.

Designing and delivering training

Early in our CMS implementation, we started thinking ahead and planning for training to help writers and editors with the transition to the new tools and the new writing approach. We created a CMS training plan that included

    • short presentations and demos designed to familiarize writers with the CMS and to introduce people to topic-based writing and DITA


    • workshops on information typing, structured writing, and DITA


  • tutorials for using the CMS (developed in-house)

Today, all new hires (both full-time employees and co-op students) and writers who are ready to move content into the CMS attend four in-house training sessions: a hands-on DITA workshop, a CMS demo, and two in-class CMS tutorials. To complement in-class CMS training, we also have several CMS training videos that writers can use to practice tasks in the CMS at their own pace and a CMS handbook that includes step-by-step instructions for using the CMS.

We continue to assess our DITA and CMS training, looking for opportunities to make adjustments and additions to better meet the needs of writers. Recently, for example, we identified a need for training on design patterns and are working to develop a “lunch and learn” that provides background information and hands-on activities that will help writers familiarize themselves with our design patterns and how to use them.

Moving forward: Looking to the future

Now what? With our content analysis and conversion process for production content in full swing, we’ll continue to develop authoring guidelines and training for writers who are moving content into the CMS. We’ll also be looking at ways to provide more support and advanced training for writers who are already working in the CMS (creating topics, reusing content, working on maintenance content, and so on). In a nutshell, we’ll continue to tackle our CMS implementation one step at a time, meeting challenges, solving problems, and of course, celebrating our successes.

Jennifer Krul is a technical editor in the Documentation Services team at Research In Motion Limited (RIM). RIM recently implemented a content management system based on DITA XML. She can be reached at This article represents the personal opinions of the author and is not in any way endorsed by RIM.

Share your ideas!

If you have a topic you think would make a good article for a future issue of the e-newsletter please send it to Articles are typically between 500 – 1000 words in length. We look forward to having our e-newsletter readers weigh-in!