choosing a content management system (cms) for dita
TRANSCRIPT
tools of the trade
A
H O W T O F I N D T H E R I G H T F I T BY FRANCE BARIL, Member
I " he purpose of content management systems (CMSs) is to make content development and delivery
processes more effective. CMSs are useful when multiple contributors need to collaborate or when large amounts of information must be created, searched, and retrieved.
As more organizations consider CMSs, they are also adopting the Darwin Information Typing Architecture (DITA), an XML-based system for producing reusable content for multiple delivery formats. This article explains steps for selecting a CMS that supports both DITA and your organization's processes.
DITA Specificities To choose the right CMS for DITA,
you must first understand DITA's main characteristics:
Many files. Creating a manual with Word or FrameMaker meant managing one file per book or per chapter. DITA, with its topic-based approach, is closer to the Web model, where each topic is saved in a separate file. The ability to store, manage, and retrieve many small files is a very important factor when choosing a CMS for DITA.
Many links. DITA's topic-based approach means that relationships between subjects are not built in a lin
ear fashion. Instead, topics are linked though relationship tables or See also links. Moreover, all reuse—whether the reuse of topics within Ditamaps or the reuse of content segments with the <conref> mechanism—is accomplished through linking. The ability of a CMS to manage all those links is an important aspect to consider.
XML. DITA is X M L . The ability to validate documents against the provided document type definitions (DTDs) or schemas and to search within specific X M L elements are very nice features to have in a CMS for DITA. Moreover, search features adapted to X M L abili-
22 intercom Image Zoo/Punchstock
ties to pinpoint information based on tagging can be a huge plus.
An evolving content model. D I T A is about flexibility and being able to adapt the content model to an organization's specific needs for tagging information. A CMS that supports D I T A should support the specialization mechanisms that enable the content model to evolve without extensive development or configuration.
Selecting a CMS If you're looking for a CMS, you have
many options. (For detailed comparisons of several CMS for DITA, see Bob
Doyle's article "DITA Tools from A to Z" in the April 2008 issue of Intercom.) Prices vary from zero for open source solutions to a few hundred thousand dollars for custom solutions with full DITA support. So how do you choose? If you follow the steps below, you'll be well on your way to choosing a system that meets your needs.
1. Ask yourself, Do I need a CMS, and why ? A lot of questions will come up when
shopping for a CMS. Listing priorities is a must. Your need for a CMS should be an extension of the reasons behind your move to DITA and X M L . Was your
move to DITA motivated by a need for enhanced collaboration, consistency, quality, reuse, time to market, automation, the localization process? What competitive edge were you looking for? Prioritizing your goals will help prioritize features.
2. Repeat the question: Do I need a CMS, and why ?
No, that isn't a misprint: this question is so important, you must consider it thoroughly. If you are new to DITA, don't run out and buy a CMS right away. Start small with a few prototype documents and a team of one to five users.
June 2 0 0 8 intercom 23
tools of the trade
D E F I N E Y O U R R F P I N T E R M S
When working out of a file system or a shared content repository, users wi l l be able to identify the major annoyances and the features that would be useful to them, which you can put on your list of priorities for the CMS. You may even end up reviewing workflow and processes, since topic-based authoring and X M L have a huge influence on how you work. It would be a shame to realize too late that you've missed the obvious.
3. Create a Request for Proposals (RFP). Remember, the RFP is as much for
you as for the vendors. Define your RFP in terms of needs; don ' t focus as much on features. Vendors may have alternative solutions for fixing issues that you may not have thought of. For example, if you need ful l text and metadata search, specify this—not XQuery—as a need. However, if you have other tools that use XQuery and want to be able to use the same queries on mult iple systems, you may specify that you want the vendor to support that standard.
Following are a few additional items to consider including in your RFP:
Define your context. Explain your pr ior i ties and how you wil l measure success at the end of the implementation.
Ask for support of specific D I T A features, as discussed above.
Define your workflow and processes: user roles, steps, etc. Ask the vendors how they would support that specific workflow. How flexible is it? What makes a document move from one step to the next—users, system events? Should the system perform actions as the docu-
Advantages of a CMS A CMS for D I T A should store all files necessary to create D I T A deliverables and support the organization's workflow and processes (for example, moving a topic or deliverable through the different approval levels). Some of the key features in clude the following abilities: • Perform ful l text and metadata
search on stored documents • Validate X M L content against the
DTDs or schemas • Validate or manage links in maps
and topics • Identify the users and their roles • Control access to documents: who
has access to what, when, to do what?
• Define workflows: steps f rom creation to publishing
• Assign work to a user or a group of users
• Notify users when they have work to do
• Track changes and /o r manage versions of topics, maps and other files
• Manage, track, and version final deliverables
• Publish content wi th or without use of the D I T A Open Toolkit
• Enable search and retrieval in dynamic publications hosted wi th help of the CMS, like knowledge bases or online help systems
ments move along the chain (validat ion, e-mail notification, and so on)? Define restrictions: should documents be hidden from specific users? Should access be controlled? Should certain op erations be restricted to specific users? Does the workflow adapt to alternate scenarios, and what happens as your workflow changes over time? Is workflow customizable? Ask about version-ing support: can you go back in time, and how?
Support for workflow and processes is the single most important th ing that a CMS wil l provide for your organization. I cannot overstate the importance of understanding your processes and def ining them properly. Before you start looking for a CMS, take the time to play with D I T A to see how it affects workflow and processes.
Ask for compatibility with the tools that each user group needs. For example, specify if writers need a WYSIWYG editor, if editors need to see formatted documents for review, or if they need access to the edit ing tool . Must occasional or remote users access content for review or edit ing without having to install new software? Do you need to integrate with a translation memory tool? If some users have requested that specific tools be used, ask for them, but also ask if the vendors have alternatives to propose.
Define localization needs. If you need to translate documents, make sure that the vendors' products are UNICODE-compliant at all stages.
Define publishing needs. Do you expect to be able to publish from the D I T A Open Toolkit? How wi l l i t interact with the system? Do you need to attach version numbers to deliverables? W i l l the tool enable you to produce end deliverables in all needed formats? Do you need to use the CMS as a publishing platform in order to offer advanced search capabilities to end users?
Define archiving needs. What do you need to keep? How long do you archive
2 4 intercom June 2 0 0 8
tools of the trade
items? Can you modify documents that have been released and /o r archived?
Define the technical environment. Talk to your IT team. Do they l imi t support for specific platforms? Do they have requirements for maintaining the system and runn ing regular backups? Do they have networking requirements? Are there security issues? Do they have requirements for how users and user roles are defined and handled? Include these requirements in the RFP.
Define your timeline. When do you expect to have the solution running? What are the important dates on your calendar for the selection process and for the implementation? Are you going to implement this in phases? What is your preferred approach and what can the vendor suggest?
Define your budget and ask for pricing. You may want to keep the details of your budget from vendors, but you should have an idea of the price range that you can afford based on the expected benefits. Ask vendors to define what is in cluded in the price and what is not: external editors, an FO-renderer for PDFs, translation m e m o i r tools, etc. Also ask if there are installation, integration, training, maintenance, or any other costs.
4. Send your RFP to a few preselected vendors based on your requirements or download and install open source software to evaluate.
You may want to send your RFP to development consulting firms (or internal development teams) if you plan for extra development and /o r customization around open source tools.
This is also a good time to ask for a product demo. You can ask for it before or after sending the RFP. Seeing a few products in action before sending the RFP may help you to include features that you hadn't thought of previously. However, don't be blinded by cool features that do not match your priorities list.
Product demos are very useful to help you understand how a product does what it says it can do.
5. Ask for a product evaluation from two to three runners-up among the vendors that answered your RFP or the evaluated open source solutions.
DITA Terms If you're new to DITA, following are definitions of some terms used in this article:
Ditamaps represent the book structure. They define the organizat ion of topics, the hierarchy in which they appear. Imagine it as a big table of content. Ditamaps may also define the relationships between the topics and /o r book details: the title, the author, the revision history, etc.
Specialization is a process by which users can add their own X M L tags to the basic D I T A DTDs or schemas while leveraging on existing elements. The process can be used to add a new topic structure, add elements to existing structures, or create new attributes. New elements are created based on existing elements and can inher i t their transformations and processing mechanisms, reducing the development cost.
The D I T A Open TooIMt is a reference implementat ion of the D I T A specification developed by the Organization for the Advancement of Structured Informat ion Standards (OASIS) D I T A Technical Committee. It contains the D I T A DTDs and X M L schemas, as well as samples and transformations to create documents in mult iple formats like H T M L or PDF.
An Fo Tenderer is a tool that transforms X M L expressed in the XSL-FO (XSL Formatting Objects) language in to printable output formats, most often PDF or RTF.
For more information on DITA, see the special D I T A issue of Intercom (Apr i l 2008).
Ask for a product evaluation. Have the vendors install the solution at your location or provide remote access to a solution. Play with i t : go through one or two quick publishing cycles with preselected users. The installation may not be customized to your workflow, but it wi l l give you a pretty good idea o f how well the product works. Is it as fast as the vendor claimed? Is it easy to use? Does it
mess up special characters in translated documents? Does it work well with your current tool set? W i l l i t really help you meet your goals?
The trial period is very important . It can help you choose a product that does what you identified as top priorities very well, as opposed to one that does everything you asked for, but not so well.
6. Negotiate your price. The larger the system, the better
your power to negotiate. Sometimes it is difficult to get a better price on the basic product, but you may be able to get more concurrent users for the same price, or other small extras.
Managing Change A CMS can be an expensive tool and is
l inked closely to internal processes. An organization that moves to D I T A and then buys a CMS usually causes a great deal of change for many employees. A good selection process wi l l not only help you select a tool that works for the teams i n place, i t wi l l also help the organization to better define its processes and get buy-in from its most important contributors. So now, do you really need a CMS, and what exactly do you need it to do? ©
SUGGESTED READINGS
CMSReview, www.cmsreview.com. General information about content management best practices and products.
Best Practices for Implement ing a CMS for Technical Publications, parts 1 to 3: www. infomanagementcenter. com/enews letter/200609/ftrst.htm www. infomanagementcenter. com/enews letter/'200610/ftrst.htm www. infomanagementcenter. com/enews letter/200704/third.htm
France Baril ([email protected]) owner of Architextus Inc., is a DITA/XML consultant as well as a documentation architect who helps organizations analyze their content and processes, select tools, learn about DITA and/or XML, manage the change process and develop supporting material from DTDs or schemas to XSL transformations.
June 2 0 0 8 intercom 25
Developing Effective
Operations and Maintenance
Manuals
i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i i n i i i i i i i i i i i i i i i i i i i i i
« « H * t « « M « « « » « « « + * « * * » A U T 0 * * « 5 - D I G I T 46268
112948 ICOA
MRS. PAULA N HARLOW 70378
7451 WINTON DR P309
INDIANAPOLIS IN 4 6 2 6 8 - 5 1 0 3