Selecting a Component Content Management System for DITA

Home/Publications/Best Practices Newsletter/2008 – Best Practices Newsletter/Selecting a Component Content Management System for DITA

 

CIDM

October 2008


Selecting a Component Content Management System for DITA


CIDMIconNewsletterScott Wolff, WOLFF & Associates, LLC

Numerous organizations implementing structured authoring and single sourcing are using DITA. If your organization is thinking about buying a CMS and either has plans to or has implemented DITA, it is important to know what CMS features are required to support DITA. To review example screenshots of the DITA CCMS features discussed in this article, see the presentation “Selecting a Content Management System for DITA” at either the CIDM website <http://www.cm-strategies.com/information/pdf/Wolff.pdf> or by visiting <http://www.scottwolff.com/Whitepapers1.aspx>.

What is DITA?

DITA (Darwin Information Typing Architecture) is an XML vocabulary or schema, a set of predefined markup tags that authors place around content to label their information.

Why use DITA?

Why have so many organizations become excited about such a simple idea? DITA offers important benefits, such as

  • modularized architecture for creating reusable topics
  • virtual documents captured as maps
  • a task-focused design, facilitating action-oriented, to-the-point communication
  • a ready-to-use production environment
  • automated desktop publishing
  • specialization that remains general during processing
  • single-sourced content for hardcopy, help, and the web publication
  • reliance on open standards and the OASIS standards community, which makes DITA application-independent.

Open standards help to ensure that your organization can take advantage of the latest technological innovation without adverse impact to your content assets.

What is a CCMS?

A Component Content Management System (CCMS) differs from other content management systems in that it is designed to manage documents as a set of components or reusable parts. Strictly speaking, DITA does not require a CCMS or even a Document Management System (DMS) to support content reuse. DITA does not rely on CCMS component linking to implement content reuse; rather, DITA uses linking and DITA maps to assemble documents from topics and components.

Each topic becomes a separate component that requires management. Often hundreds of topics are produced per document. As you can imagine, the proliferation of topics can quickly become intractable. The ability to manage topics effectively plays a vital role in meeting any content reuse objectives. A CCMS allows you to control access rights and workflow and status at the topic level. Most CCMS applications add business logic in addition to the rules enforced by the formal specification of a DTD, providing additional control over how your information is managed and produced.

Choosing a CCMS

Choosing the right CCMS is an important task. Organizations can experience “buyers remorse” immediately after implementing a CCMS if they

  • rushed into purchasing a system without time to conduct a pilot
  • didn’t consider goals and requirements as well as alternative applications
  • relied on “vendor speak,” which clouded their decision making

Before you launch into buying a CCMS, I recommend that you conduct a content analysis, develop your information model, and implement DITA on at least one publication. Then, consider the following process for identifying and purchasing a CCMS.

Nine steps for choosing a CCMS:

  1. Define your goals
  2. Define your requirements
  3. Prioritize your requirements
  4. Identify potential CCMS products
  5. Send out an RFP (Request For Proposal)
  6. Conduct demos
  7. Select a candidate
  8. Conduct a pilot
  9. Make a purchase decision

Define Application Requirements

Before purchasing a CCMS, you will need to define your application requirements. These requirements should reflect the customer, business, and process goals. Start by establishing what the expected benefits are. They may include reducing the time to market, improving the quality and consistency of documentation, or reducing the cost of producing and managing content; or perhaps you have limited resources and need to build a scalable process to meet the growing demands for content by your customer base. Be as specific as possible. Break these objectives into specific CCMS feature-related categories by defining how you want the CCMS to support the defined objectives. Consider the following categories:

CCMS Feature Categories:

  • Standards support (such as DITA)
  • Ease of use
  • Permissions and rights
  • Authoring integration
  • Application compatibility
  • Import and export
  • Reuse and link management
  • Search and categorization
  • Version and edition management
  • Translation and localization support
  • Workflow
  • Publication
  • Reporting
  • System administration

Once you have established the application requirements, consider what requirements you have for the application vendor. Set a budget for licensing and support as well as vendor expectations regarding your need for responsiveness, support, and training.

Specific CMS Features that Support the DITA Information Model

If your information model is DITA-based, having a CCMS that supports DITA will greatly improve the overall usability and effectiveness of your solution. The following lists the most relevant DITA-related CMS features on the market today. By considering these thirteen features as part of your overall solution, you will be able to determine if the CCMS vendor can provide the functionality you require.

  • DITA editor integration
  • DITA map editor
  • Attribute editor
  • Relationship table editor
  • Topic version management
  • Conref support
  • Cross reference links
  • Map imports/exports
  • Search where used/what used
  • File differencing for DITA maps
  • Specialization
  • Conditional publisher
  • DITA Open Toolkit integrated publisher

DITA Editor Integration

Many CCMS application APIs (Application Programming Interface) are integrated out-of-box with popular DITA authoring applications such as Arbortext, XMetaL, and FrameMaker. Be certain that the XML editor you have chosen is supported by the CCMS. Additionally, some CCMS application vendors provide their own web-based topic authoring interface. Browser-based editors can be very useful for enabling direct Subject-Matter Expert (SME) contributions.

As an example, Content Technologies and Inmedius offer a web-based author interface that is designed for SME contributions. Another unique innovation for authoring is the IDE (Integrated Development Environment) offered by IXIASOFT. The IXIASOFT user interface provides a fully integrated view of the XMetaL editor and the CMS, building on the concept that a CCMS is really an extended authoring solution. With IXIASOFT’s integrated IDE, the editor and CMS interface appear to the end user as a single application within a single window.

DITA Map Editor

DITA maps are used to assemble documents from component topics and other DITA maps. Since the topics are stored and managed in the CCMS, it is important to build the DITA map-to-topic associations within an editor provided by the CCMS application. This process will ensure that the CCMS bi-directional links are updated to reflect the content relationships. A CCMS DITA Map editor should allow the author to work within the CMS to view existing relationships and build new relationships among the topics stored within the CCMS. Better DITA map editors provide intuitive drag-and-drop topic adding and arrow buttons for promotion and demotion of topics within the map hierarchy.

Attribute Editor

DITA information types come equipped with a number of important predefined attributes such as those used for conditional publishing or capturing information about author. The system you choose should provide an easy interface for editing standard DITA attribute values. Additionally, you may require additional power-user features to perform mass updates of attribute values. For an example of attribute editing, see the Vasont Systems CMS.

Relationship Table Editor

An important best practice for authors using DITA is to build topic-to-topic relationships (crosslinks) using the DITA map “relationship table.” This table ensures that topic dependencies are maintained at the document level, rather than embedded within the topic. Embedding specific links within topics greatly reduces their reusability. A few CCMS applications provide an editor with an intuitive user interface for defining relationship tables. Most CCMS applications still require that the author create the relationship table with their DITA editor. For a nice example of a relationship table editor provided by the CCMS, see IXIASOFT’s DITA CMS Framework.

Topic Version Management

DITA alone cannot manage multiple versions of content associated with a single DITA Map. Over time, authors make updates to topics and new versions often replace older versions of topics. However, the old version of a topic may need to be maintained for regulatory requirements or other reasons. Under such circumstances, a CCMS can provide additional support by tracking the relationship between multiple versions of the same topic within a ditamap. For an example of version-managed DITA maps, see Trisoft’s Publication Manager.

Conref Support

DITA Content References enable topic components to be reused within other topics. Effective conref support by a CCMS requires a tight integration with your chosen DITA editor. Content references are commonly used to standardize hazard warnings. For example, all the electrical hazard warnings can be created in a single concept topic called Electrical Hazards. Then, as authors create new topics, they use a conref to link to the specific hazard warning they need.

The CCMS is configured so that only those with authority to make changes to the hazard warning are allowed to do so. The best CCMS applications provide in-context visualization, so that you can see both the text and the graphics to assist in selecting the correct content to reuse. They also are context-aware so that the author is prevented from attempting to reuse the wrong type of content unit for the chosen insertion point. To see examples of how conref support should be implemented, see the Trisoft CMS, IXIASOFT’s DITA CMS Framework, and Vasont Systems.

Cross Reference Links

Cross References also require integration with the selected DITA editor, enabling the author to place a cross reference within a topic and then support the author’s search of the CCMS for the topic to reference.

Map Imports/Exports

The ability to import and export content with structure has long been a requirement of CCMS applications. A DITA map is used to aggregate topics to communicate about a subject with a specific purpose in mind. The construct of a DITA map is fundamental to the authoring process. A DITA-aware CMS should provide facilities to manage imports and exports of DITA maps with their associated topic files.

The import process requires that the CCMS can resolve the references within the DITA maps to locate the respective topic files on the server and provide the user with appropriate choices about how to handle the associated topic files, such as replicating the folder structure on the CCMS. The CCMS should be able to manage DITA maps embedded within other DITA maps and resolve references to resources such as graphics. The best systems provide a confirmation feature to allow the user to see a list of all the topic files selected before importing. As an example, see Empolis’s e:CLS.

Search Where Used/What Used

The “Where-Used” and “What-Used” search functions are important tools for authors to effectively reuse content.

  • Where Used allows authors to select a potential topic and quickly locate all other document instances that reference the same topic, allowing the author to see how and where the topic was used in the past. As a result, the author can select the most appropriate topic. Some applications can also apply the same Where-Used functionality at the content-unit level for conref links if the conrefs were handled correctly by the CCMS.
  • What Used enables a quick search in the reverse direction within the document hierarchy so that the author can see what other topics are referenced by a specified document. This feature is useful because authors often know which product models are most similar to the product they are currently documenting. Authors thus can locate the topic from a past document.

Using these two features together allows authors to quickly locate and choose the best topic to reuse or determine whether a new topic is needed. See the Empolis e:CLS for an example of push-button toggling of the Where-Used, What-Used views.

File Differencing for DITA Maps

The ability to quickly compare different versions of the same document can be helpful to authors trying to assess what has changed since the previous release of a document. A CCMS supports this process by providing a DITA map difference tool so that the author can visually see a color-coded listing of changes. For example, IXIASOFT allows you to see a side-by-side comparison of DITA maps to identify what topics or maps were added, removed, or shared in common.

Specialization

DITA Specialization allows large organizations with multiple divisions to create consistent branding by sharing the same stylesheets and process applications, while allowing individual departments to add business-unit-specific information types. DITA effectively addresses this age-old problem by empowering individual business units to “specialize” the information model without requiring a mandate or corporate- wide agreement.

CCMS solutions often require some configuration to accommodate changes to the information model. Application providers can build in functionality so that little or no additional CCMS configuration is required when one of your business units decides to use a specialization. Ideally, you will only need to load your new schema and edit your catalog file to tell the system where the new DTDs are located. The Trisoft CMS provides a system that addresses specialization in this seamless fashion.

Conditional Publisher

Conditional publishing allows authors to include or exclude content based on the values of attributes set on the content. This operation can occur at the map, topic, or content-unit level, and allows variant documents to be managed as a single document. The feature prevents the proliferating of many similar topics with only minor differences to address specific audience or platform requirements. A CCMS can allow users to set conditional values at the time of publishing. If the DITA Open Toolkit is used, the user interface creates a “ditaval” file for you. XyEnterprise and Astoria provide an easy-to-use interface for setting and saving conditional-publishing settings.

DITA Open Toolkit Integrated Publisher

CCMS solutions often integrate with a publishing application, although some rely on out-of-box authoring tools to provide that functionality. DITA-enabled CCMS applications can integrate with the DITA Open Toolkit, a valuable option if you determine that the Toolkit will meet your publishing requirements.

The DITA Open Toolkit comes equipped with basic stylesheets to produce common deliverable formats such as PDF, HTML Help, and HTML pages. CCMS applications, which support the DITA Toolkit, allow organizations to use the same formatting applications to get consistent, predicable results no matter which business unit is publishing. However, the Toolkit is not required to achieve this level of consistency. If your systems use the same XSLT and XSL-FO applications and you build references the same stylesheets, you should get the same results. However, the DITA Open Toolkit integrates the build processing using ANT scripts, saving both time and money. A number of CCMS applications are integrated with the DITA Open Toolkit, including Astoria, Trisoft, and DITA Exchange.

If your organization is considering which CCMS application to buy and you have chosen DITA as your information model, understanding how content management features interact with and support the DITA information architecture can help ensure that you get the best system to address your DITA requirements. If you are considering a CCMS for DITA, there are some important rules.

For successful CCMS selection, you should

  1. first implement DITA before investing in a CCMS
  2. define your business and end-user goals before defining your CCMS requirements
  3. always conduct a pilot before purchasing a CCMS
  4. focus on the information; information is the asset; CCMS applications just help manage the asset

The CCMS is an important extension of the authoring platform, assisting authors in locating, reusing, and assembling information. Although you can get along without a CCMS, having the right one can help you manage content reuse, facilitate collaboration for distributed development teams, and control process consistency. CIDMIconNewsletter

Scott WolffScott Wolff

WOLFF & Associates, LLC

scott@scottwolff.com

Scott Wolff is a partner of WOLFF & Associates, LLC., a consulting firm dedicated to providing expertise in technical information design, reuse and single sourcing using DITA. As a consultant, Scott brings over ten years of experience with single sourcing, CMS program management and provides: DITA training, ROI analysis, business transformation planning, audience analysis, task analysis, metadata planning, information modeling, format analysis, DITA specialization and DTD development, XSL-FO or Styler development, and application requirements planning and selection for content management. Scott has created Wolff & Associates to offer a comprehensive engineering approach to designing topic based information and selecting the best applications to author, manage and deliver your publications. Prior to WOLFF & Associates, Scott worked for Hewlett Packard leading aspects of Content Management, Technical Publications Management, Software Development, and Manufacturing Operations. Scott holds a BS in Industrial Engineering, an ME in Industrial Engineering, and an MS in Computer Science. WOLFF & Associates “engineered solutions for technical publications”.