tools of the trade

H O W TO FIND T H E RIGHT FIT

" 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 ( D I T A ) , an
XML-based system for producing reusable content for multiple delivery formats. This article explains steps for selecting a C M S that supports both D I T A
and your organization's processes.

22

BY FRANCE BARIL, Member

DITA Specificities
To choose the right C M S for D I T A ,
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

ear fashion. Instead, topics are linked

though relationship tables or See also
links. Moreover, all reusewhether
the reuse of topics within Ditamaps or
the reuse of content segments with the
<conref> mechanismis accomplished
through linking. T h e ability of a C M S to
manage all those links is an important
aspect to consider.

store, manage, and retrieve many small

files is a very important factor when
choosing a CMS for DITA.

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 C M S for DITA. Moreover,
search features adapted to X M L abili-

Many links. DITA's topic-based approach means that relationships between subjects are not built in a lin-

intercom

XML. D I T A is X M L . T h e ability to val-

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 C M S that supports D I T A should support the specialization mechanisms
that enable the content model to
evolve without extensive development
or configuration.

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
D I T A 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.

If you're looking for a CMS, you have

many options. (For detailed comparisons of several CMS for D I T A , see Bob

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 C M S should
be an extension of the reasons behind
your move to D I T A and X M L . Was your

June 2 0 0 8

intercom

Selecting a C M S

move to D I T A 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 C M S right away.
Start small with a few prototype documents and a team of one to five users.

23

tools of the trade

DEFINE YOUR
RFP IN T E R M S

W h e n w o r k i n g out of a file system or a

shared content repository, users will be
able to identify the major annoyances
and the features that w o u l d be useful
to them, w h i c h you can p u t on your list
of priorities for the CMS. You may even
end up reviewing workflow and processes, since topic-based a u t h o r i n g a n d
X M L have a huge influence on how you
work. It w o u l d 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 m u c h for
you as for the vendors. Define your RFP
in terms of needs; d o n ' t focus as m u c h
on features. Vendors may have alternative solutions for fixing issues that you
may n o t have t h o u g h t of. For example, if
you need full text and metadata search,
specify thisnot XQueryas a need.
However, if you have other tools that use
X Q u e r y and want to be able to use the
same queries on m u l t i p l e systems, you
may specify that you want the vendor to
support that standard.
Following are a few additional items
to consider i n c l u d i n g in your RFP:
Define your context. Explain your p r i o r i ties and how you will measure success at
the e n d 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 w o u l d support that specific workflow. H o w flexible is it? What makes a
document move f r o m one step to the
nextusers, system events? Should the
system p e r f o r m actions as the docu-

24

Advantages
of a C M S

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 t h r o u g h the different approval
levels). Some of the key features i n clude the following abilities:
Perform full 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
C o n t r o l access to documents: w h o
has access to what, when, to do
what?
Define workflows: steps f r o m creation to publishing
Assign w o r k to a user or a group of
users
Notify users when they have w o r k
to do
Track changes a n d / o r manage
versions of topics, maps and other
files
Manage, track, and version final
deliverables
Publish content w i t h or w i t h o u t
use of the D I T A O p e n T o o l k i t
Enable search and retrieval in dynamic publications hosted w i t h
help of the CMS, like knowledge
bases or o n l i n e help systems

intercom

ments move along the chain (validat i o n , e-mail notification, and so on)?
Define restrictions: should documents
be h i d d e n f r o 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 workflow customizable? Ask about versioni n g support: can you go back in time,
and how?
Support for workflow and processes is
the single most i m p o r t a n t t h i n g that a
CMS w i l l provide for your organization.
I cannot overstate the importance of
understanding your processes and def i n i n g them properly. Before you start
l o o k i n g for a CMS, take the time to play
w i t h D I T A to see how it affects workflow
and processes.
Ask for compatibility with the tools that
each user g r o u p 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 editing t o o l . Must occasional or
remote users access content for review
or e d i t i n g w i t h o u t having to install new
software? Do you need to integrate w i t h
a translation m e m o r y 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 U N I C O D E c o m p l i a n t at all stages.
Define publishing needs. Do you expect
to be able to publish f r o m the D I T A
O p e n Toolkit? H o w w i l l it interact w i t h
the system? Do you need to attach version numbers to deliverables? W i l l the
t o o l 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 e n d users?
Define archiving needs. W h a t do you
need to keep? H o w l o n g do you archive

June 2 0 0 8

tools of the trade

items? Can you modify documents that
have been released a n d / o r archived?
Define the technical environment. Talk
to your IT team. Do they l i m i t support
for specific platforms? Do they have requirements for m a i n t a i n i n g the system
and r u n n i n g 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. W h e n do you expect to have the solution running? W h a t
are the i m p o r t a n t dates on your calendar for the selection process and for
the implementation? Are you going to
i m p l e m e n 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, b u t you should
have an idea of the price range that you
can afford based on the expected benefits. Ask vendors to define what is i n 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, traini n g , 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 a n d / o r customization
a r o u n d 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.

DITA Terms

If you're new to D I T A , following are

definitions of some terms used in this
article:
Ditamaps
represent
the
book
structure. They define the organizat i o n of topics, the hierarchy in w h i c h
they appear. Imagine it as a b i g table
of content. Ditamaps may also define
the relationships between the topics
a n d / o r book details: the title, the author, the revision history, etc.
Specialization is a process by w h i c h
users can add their o w n X M L tags
to the basic D I T A DTDs or schemas
while leveraging on existing elements. T h e 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 i n h e r i t their transformations and processing mechanisms,
reducing the development cost.
T h e D I T A Open TooIMt is a reference i m p l e m e n t a t i o n of the D I T A
specification developed by the Organization for the Advancement of
Structured I n f o r m a t i o n Standards
(OASIS) D I T A Technical C o m m i t tee. It contains the D I T A DTDs and
X M L schemas, as well as samples and
transformations to create documents
i n m u l t i p l e formats like H T M L o r
PDF.
An Fo Tenderer is a tool that transforms X M L expressed i n the XSL-FO
(XSL Formatting Objects) language
i n t o printable o u t p u t formats, most
often PDF or RTF.
For more i n f o r m a t i o n on D I T A ,
see the special D I T A issue of Intercom
( A p r i l 2008).

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.

Ask for a product evaluation. Have

the vendors install the solution at your
location or provide remote access to a
solution. Play w i t h it: go t h r o u g h one or
two quick publishing cycles w i t h preselected users. The installation may n o t
be customized to your workflow, but it
will give you a pretty good idea o f how
well the p r o d u c t works. Is it as fast as the
vendor claimed? Is it easy to use? Does it

June 2 0 0 8

intercom

Product demos are very useful to help

you understand how a p r o d u c t does what
it says it can do.

mess up special characters in translated

documents? Does it w o r k well w i t h 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 p r o d u c t that does
what you identified as top priorities very
well, as opposed to one that does everyt h i n g 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 m o r e concurrent users for the same
price, or other small extras.
Managing Change
A CMS can be an expensive tool and is
l i n k e d 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 will n o t only
help you select a tool that works for the
teams i n place, i t will also help the organization to better define its processes
and get buy-in f r o m its most i m p o r t a n t
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 I m p l e m e n t i n g 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 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.

25

Developing
Effective
Operations and
Maintenance
Manuals

iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiiii
H*tM+***AUT0**5 - DIGIT
112948
MRS.
7451

PAULA

46268
ICOA

WINTON

INDIANAPOLIS

HARLOW
DR
IN

70378
P309

46268-5103