Sunteți pe pagina 1din 5

tools of the trade

A

tools of the trade A H O W T O FIN D I " he purpose
tools of the trade A H O W T O FIN D I " he purpose
tools of the trade A H O W T O FIN D I " he purpose

H O W

T O

FIN D

I " he purpose of content manage-

ment systems (CMSs) is to make

content development and delivery

processes more effective. CMSs are use- ful 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 Infor- mation Typing Architecture (DITA), an XML-based system for producing reus- able content for multiple delivery for- mats. This article explains steps for se- lecting a CM S that supports both DIT A and your organization's processes.

22

TH E

RIGH T

FI T

DITA Specificities To choose the right CM S 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. Th e 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 ap- proach means that relationships be- tween subjects are not built in a lin-

intercom

BY FRANCE BARIL, Member

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. Th e ability of a CM S to manage all those links is an important aspect to consider. XML. DIT A is XML . Th e ability to val- idate 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 CM S for DITA. Moreover, search features adapted to XM L abili-

Image Zoo/Punchstock

ties to pinpoint information based on tagging can be a huge plus. An evolving content model. DIT A is

about flexibility and being able to adapt the content model to an organization's specific needs for tagging information.

A CM S that supports DIT A should sup-

port 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 compari- sons of several CM S for DITA , see Bob

June

200 8

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 CM S should be an extension of the reasons behind your move to DIT A and XML . Was your

intercom

move to DIT A motivated by a need for enhanced collaboration, consistency, quality, reuse, time to market, automa- tion, the localization process? What competitive edge were you looking for? Prioritizing your goals will help priori- tize features.

2. Repeat the question: Do I need a CMS, and why ? No, that isn't a misprint: this ques- tion is so important, you must consider it thoroughly. If you are new to DITA, don't ru n out and buy a CM S right away. Start small with a few prototype docu- ments and a team of one to five users.

23

tools of the trade

tools of the trade When workin g out of a file system or a shared content
tools of the trade When workin g out of a file system or a shared content
tools of the trade When workin g out of a file system or a shared content

When workin g out of a file system or a shared content repository, users will 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 pro- cesses, since topic-based authorin g an d 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 alterna- tive solutions for fixing issues that you may not have thought of. For example, if you need full 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 multipl e systems, yo u 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 priori - ties and how you will measure success at the end of the implementation. Ask for support of specific DIT A fea- tures, as discussed above. Define your workflow and processes: user roles, steps, etc. Ask the vendors how they would support that specific work- flow. Ho w 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 DIT A should store all

files necessary to create DIT A deliv- erables and support the organiza- tion's workflow and processes (for example, moving a topic or deliver- able through the different approval levels). Some of the key features in- clude the following abilities:

• Perform full text and metadata search on stored documents

• Validate XM L content against the DTDs or schemas

• Validate or manage links in maps and topics

• Identify the users and their roles

Contro l access to documents: wh o

has access to what, when , to do what?

• Define workflows: steps fro m cre- ation 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 with or without use of the DIT A Open Toolkit

• Enable search and retrieval in dy- namic publications hosted with help of the CMS, like knowledge

bases or onlin e help systems

24

intercom

DEFINE

RFP

YOU R

I N TERM S

ments move along the chain (valida- tion, e-mail notification, and so on)? Define restrictions: should documents be hidde n fro m 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 work- flow customizable? Ask about version- ing support: can you go back in time, and how? Support for workflow and processes is the single most important thing that a CMS will provide for your organization.

I cannot overstate the importance of

understanding your processes and de- fining them properly. Before you start looking for a CMS, take the time to play wit h DIT A to see how it affects workflow and processes.

tools that

each user group needs. For example, specify if writers need a WYSIWYG edi-

tor, if editors need to see formatte d doc- uments for review, or if they need access to the editing tool. Must occasional or remote users access conten t for review

or editing without having to install new

software? Do you need to integrate with

a translation memory tool? If some us-

ers have requested that specific tools be used, ask for them , bu t 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- complian t at all stages. Define publishing needs. Do you expect to be able to publish from the DIT A Open Toolkit? How will it interact with the system? Do yo u need to attach ver- sion numbers to deliverables? Will the tool enable you to produce end deliv- erables in all needed formats? Do you need to use the CMS as a publishing platform in order to offer advanced search capabilities to en d users?

Define archiving needs. Wha t do you need to keep? How long do you archive

Ask for compatibility with the

June

200 8

items? Can you modify documents that have been released and/o r archived? Define the technical environment. Talk to your IT team. Do they limit support for specific platforms? Do they have re- quirements for maintaining the system and running regular backups? Do they have networking requirements? Are there security issues? Do they have re- quirements for how users and user roles are defined and handled? Include these requirements in the RFP. Define your timeline. Whe n do yo u ex- pect to have the solution running? What are the important dates on your calen- dar for the selection process and for the implementation? Are you going to implemen t 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 ben- efits. Ask vendors to define what is in- cluded in the price and what is not: ex- ternal editors, an FO-renderer for PDFs, translation memoi r tools, etc. Also ask if there are installation, integration, train- ing , 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 de- velopment consulting firms (or internal development teams) if you plan for ex- tra development and/or customization around open source tools.

This is also a good tim e 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. Howev- er, 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 ca n do .

5. Ask for a product evaluation from two to three runners-up among the vendors that an- swered your RFP or the evaluated open source solutions.

June

200 8

DITATerms

If you're new to DITA, following are definitions of some terms used in this article:

Ditamaps represent the book structure. They define the organiza- tion 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/or book details: the title, the au- thor, the revision history, etc. Specialization is a process by which users can add their ow n XM L tags to the basic DIT A DTDs or schemas while leveraging on existing ele- ments. The process can be used to add a new topic structure, add ele- ments to existing structures, or cre- ate new attributes. New elements are created based on existing elements and can inherit their transforma- tions and processing mechanisms, reducing the development cost. The DIT A Open TooIMt is a refer- ence implementation of the DIT A specification developed by the Or- ganization for the Advancement of Structured Information Standards (OASIS) DIT A Technical Commit- tee. It contains the DIT A DTDs and X M L schemas, as well as samples and transformations to create documents in multiple formats like HTM L or PDF.

An Fo Tenderer is a too l that trans-

forms XM L expressed in the XSL-FO (XSL Formatting Objects) language into printable output formats, most often PDF or RTF. For more information on DITA, see the special DIT A issue of Intercom (April 2008).

Ask for a product evaluation. Have the vendors install the solution at your locatio n or provide remote access to a solution. Play with it: go through one or two quick publishing cycles with prese- lected users. The installation may not be customized to your workflow, but it will give you a pretty good idea o f how well the produc t works. Is it as fast as the vendo r claimed? Is it easy to use? Does it

intercom

tools of the trade

mess up special characters in translated documents? Does it work well with your current tool set? Will 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 every- thing 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

linked closely to internal processes. An organization that moves to DIT A and the n buys a CMS usually causes a great deal of change for many employees.

A good selection process will not only

help you select a tool that works for the

teams i n place, it will also

help the or-

ganization to better define its processes and get buy-in from its most important

contributors. So now, do

yo u really need

a

CMS, an d what exactly

do yo u need it

to

do? ©

SUGGESTED READINGS

General

information about content management best practices and products.

CMSReview,

www.cmsreview.com.

Best Practices for Implementing 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 (france.baril@architexttis.com) owner of Architextus Inc., is a DITA/XML consultant as well as a documentation ar- chitect who helps organizations analyze their content and processes, select tools, learn about DITA and/or XML, manage the change pro- cess and develop supporting material from DTDs or schemas to XSL transformations.

25

Developing Effective Operations and Maintenance Manuals iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiii i
Developing Effective Operations and Maintenance Manuals iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiii i
Developing Effective Operations and Maintenance Manuals iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiii i
Developing Effective Operations and Maintenance Manuals iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiii i
Developing Effective Operations and Maintenance Manuals iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiii i
Developing Effective Operations and Maintenance Manuals iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiii i
Developing Effective Operations and Maintenance Manuals iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiii i

Developing Effective Operations and Maintenance Manuals

iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiii i ««H*t««M «««»«««+*«**»AUT0**«5- DIGIT 46268
iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiii i
««H*t««M «««»«««+*«**»AUT0**«5- DIGIT
46268
112948
ICOA
MRS. PAULA N HARLOW
7037 8
7451
WINTON DR
P30 9
INDIANAPOLIS IN
46268-5103
DIGIT 46268 112948 ICOA MRS. PAULA N HARLOW 7037 8 7451 WINTON DR P30 9 INDIANAPOLIS
DIGIT 46268 112948 ICOA MRS. PAULA N HARLOW 7037 8 7451 WINTON DR P30 9 INDIANAPOLIS