Best Practices for Implementing a CMS for Technical Publications – Part 3

Home/Publications/CIDM eNews/Information Management News 04.07/Best Practices for Implementing a CMS for Technical Publications – Part 3

Scott Wahl, Research In Motion

Read Part 1 and Part 2 in earlier issues of our e-newsletter.

Part 3 of 3 – Implementing a CMS

You have thought carefully about whether you and your department are ready to move to a CMS. You have planned out your requirements, evaluated different vendors, and selected a system to implement. You have completed a pilot and have now implemented a working system.

Now comes the hard part: moving your content into the CMS and managing the transition of your team to using the CMS. This is where all your thorough planning and analysis can come apart. You need to manage the implementation process as carefully as you would any other project to make sure that, in the end, you meet the objectives you set out in the beginning – to improve quality, increase productivity, and lower costs.

Focus first on content: analyze, redesign, rewrite

When implementing a CMS, stay focused on what is most important – the content that your team creates and publishes. There is no point in putting content into the CMS that is not useful to your customers, does not meet your quality standards, or is not reusable. Take the time to do a thorough analysis of your content.

If you have thousands of pages of legacy content, consider the right approach for moving that content into the CMS. Perhaps only a small percentage of that content needs to be updated for a given product release. Do not spend time developing tools to automate the conversion of content from one format (such as Adobe FrameMaker) to XML. Moving less content into the CMS at a slower pace is better than completing a wholesale conversion of problematic (or useless) content. The old adage applies here: garbage in, garbage out. The time, effort, and cost of implementing a CMS will be wasted if you do not take the time to look closely at your content and, if necessary, rebuild it from the ground up.

If you do not revise and improve your content as you move it into a new system, you never will. And if you are not going to spend time making sure the content is as good as it can be, why would you spend time putting it into a new system in the first place?

Analyze content

As with any other activity, spend some time up front planning what you are going to do, who is going to do it, and what you expect to achieve. You will probably not be able to analyze all your existing content at the same time, so consider which content you want to tackle first. You might focus on content that is already in good shape or content where the potential benefits from using a CMS are the greatest. The content analysis process can take a significant amount of time and effort to do properly, and it will almost certainly take longer than you expect.

Decide who will do the analysis for a given set of content. Ideally, a lead writer (or team of writers), an editor, and an information architect should collaborate on the analysis, working together to develop standards, guidelines, and resources to support future content analysis and conversion work.

Start with an audience analysis. If you don’t already have audience profiles, create one for each type of content. Having a clear understanding of who you are writing for will help you determine when to rewrite or delete content and how to reorganize content.

Some steps to consider during content analysis:

  • Identify opportunities for reuse.
  • Identify topics that can be deleted (for example, redundant topics or topics that are not goal-based).
  • Verify that content is minimalist.
  • Verify that headings are goal-based and follow the conventions in your style guide.
  • Classify topics into topic types (such as concept, task, or reference) according to your information model.
  • Classify content within topics according to your information model.
  • Determine requirements for attributes or conditional text.
  • Identify areas that require more research (gaps in existing content).
  • Identify topics that need to be separated into more than one topic; provide suggestions for headings, topic type, goals, and so on for new topics.
  • Identify related topics.

Consider creating a spreadsheet or other document where the writer, information architect, and/or editor can record the results of their analysis.

Revise and convert content

After you have completed your content analysis, the next step is to revise content based on the final results of this analysis. Revising content might be fairly straightforward – such as deleting unnecessary topics or renaming topic headings – or quite involved – such as researching identified gaps in content or doing further user/task analysis to determine user needs. Regardless of who does these tasks, the team that performed the original analysis needs to stay involved, to make sure the revisions are completed as expected, and to make sure everyone is satisfied with the final results. Agree up front on how the whole team will review the revised content.

You can choose to revise content either before or after you convert the content to XML. In general, however, you should revise content before moving it into the CMS. It is much easier for writers and editors to focus on improving content when they are not also struggling to learn a new set of tools.

After you revise content, you can now convert it to XML This conversion task should be quite mechanical if the content has been thoroughly revised already.

After content is in XML, the lead writer should schedule another review with an information architect or editor to verify that content is organized as expected and that it meets any authoring guidelines that you have in place. Then complete your standard editing process to make sure that content meets all your editorial standards. Make sure that content in your CMS is flagged as ‘draft’ or ‘work in progress’ until editing is complete.

Build documents

After you move content into the CMS, you need to shift your focus to building information deliverables. With DITA, building information deliverables means building topic maps and relationship tables. Have an information architect work with a lead writer to plan the organization of topics into various deliverables, build the relationship tables, and test out publishing in the target formats.

Consider creating a map specification for each deliverable to organize topics and to identify related topics before building maps or relationship tables in the CMS. The map specification can be based on content specifications created earlier in the process. Lead writers can typically start building ditamaps while content is going through final editing and revision cycles.

Make sure that an editor or information architect reviews the map specification or the map itself:

  • Verify that headings are consistent and goal-based; verify that they follow the conventions in your style guide.
  • Verify that topics are divided appropriately into sections.
  • Verify that topics flow logically.

Test publishing outputs from your CMS or publishing system to verify that the deliverables appear correctly in the formats you need.

Develop authoring guidelines as you go

Assign someone, such as a lead editor or information architect, to create authoring guidelines in collaboration with other writers and editors. These guidelines, which will complement your existing style guide, will provide specific information on writing and organizing information in XML – from which topic types to use for different types of content to the specific tags and attributes to use within each topic type.

Although you do not need to have authoring guidelines in place before you start content analysis, you should develop and update them as you proceed. Writers will learn a lot early in the process, and you want to make sure the team performing the initial analysis captures their knowledge for future reference.

Get the right training at the right time

An important part of a CMS implementation is training. Although technical and tools training is often the focus for writers, the success of the CMS implementation really rests on the ability of writers and editors to organize and write clear, user-oriented, minimalist content in a structured writing environment. So make sure to provide training on how to do that. Even very experienced technical writers can struggle with the shift to topic-based writing. Consider having a consultant provide a customized workshop to your team on structured writing, and then assign someone to build your own in-house training program over time. A phased approach to training often works best, so that writers can complete smaller modules of training at appropriate times.

Follow a phased approach with realistic targets

It is unlikely that you will be able to do everything at once. Consider how you can take a phased approach to your CMS implementation – by content type, by project, or by team. There is definite value in maintaining momentum and keeping everyone focused to complete the move into the CMS. At the same time, content analysis and revision will almost certainly take longer than you think, and different people (or teams) will take more or less time to wrap their heads around topic-based writing and learn the new set of tools.

And always keep in mind that your CMS activities need to align with project schedules. Factor in everyone’s existing project workload when you plan CMS activities, and make sure that you can complete CMS migration of a given set of content within a project schedule.

Over-communicate at every step in the process

Failing to communicate with your team is the worst thing that you can do during your CMS implementation. Make sure that everyone knows what is happening and what everyone is working on. When you follow a phased approach, some groups will start working in the CMS long before others, so defining a process for communication becomes very important.

The technical experts, information architects, writers, editors, and others all need to talk to one another about how things are going, where they are encountering problems, and what the priorities are.  You might consider creating a steering committee or other forum for members of your team (writers, editors, information architects, technical experts) to discuss and resolve CMS issues.

At some point, you will also need to define a change management process for authoring guidelines, so that the right people are involved in vetting changes and making decisions, and so that the whole group is aware of changes.

Expect the unexpected (and leave time for it)

No matter how diligent you have been up to now, you will encounter problems of one sort or another. A few examples:

  • Your CMS will not work as expected under certain conditions.
  • You will have to develop new guidelines or processes for working in the CMS.
  • You will have to support writers or editors who struggle to learn the new system.
  • You will have to deal with inevitable conflicts between project timelines and priorities.

Celebrate success!

Do not forget as you proceed with your CMS implementation to celebrate everyone’s achievements. Acknowledge that everyone is learning a new way of working – a new way of writing, new processes, and new tools. Give everyone credit for working together to meet the objectives you set out in the first place.

In this series of three articles, Scott Wahl explores best practices for implementing a content management system (CMS) for technical publications. Scott Wahl is Director of Software Documentation & Localization at Research In Motion Limited (RIM). RIM recently implemented a content management system based on DITA XML. These articles represent the personal opinions of the author and are not in any way endorsed by RIM.

 

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close