tools of the trade
H O W TO FIND T H E RIGHT FIT
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 ( D I T A ) , an
XML-based system for producing reus-
able content for multiple delivery for-
mats. This article explains steps for se-
lecting a C M S that supports both D I T A
and your organization's processes.
22
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
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. T h e ability of a C M S to
manage all those links is an important
aspect to consider.
XML. D I T A is X M L . T h 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 C M S for DITA. Moreover,
search features adapted to X M L abili-
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 sup-
port the specialization mechanisms
that enable the content model to
evolve without extensive development
or configuration.
Selecting a C M S
If you're looking for a CMS, you have
many options. (For detailed compari-
sons of several CMS for D I T A , see Bob
June 2 0 0 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
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.
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
intercom
move to D I T 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 run out and buy a C M S right away.
Start small with a few prototype docu-
ments and a team of one to five users.
23
tools of the trade
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 pro-
cesses, 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 alterna-
tive 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 this—not XQuery—as 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 fea-
tures, 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 work-
flow. H o w flexible is it? What makes a
document move f r o m one step to the
next—users, 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 deliv-
erables and support the organiza-
tion's workflow and processes (for
example, moving a topic or deliver-
able 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 cre-
ation 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 dy-
namic publications hosted w i t h
help of the CMS, like knowledge
bases or o n l i n e help systems
intercom
DEFINE YOUR
RFP IN T E R M S
ments move along the chain (valida-
t 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 work-
flow customizable? Ask about version-
i 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 de-
f 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 edi-
tor, if editors need to see formatted doc-
uments 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 us-
ers 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 ver-
sion numbers to deliverables? W i l l the
t o o l 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 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

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 re-
quirements 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 re-
quirements 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 ex-
pect to have the solution running? W h a t
are the i m p o r t a n t dates on your calen-
dar 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 ben-
efits. Ask vendors to define what is i n -
cluded in the price and what is not: ex-
ternal editors, an FO-renderer for PDFs,
translation m e m o i r tools, etc. Also ask if
there are installation, integration, train-
i 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 de-
velopment consulting firms (or internal
development teams) if you plan for ex-
tra 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. 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 p r o d u c t does what
it says it can 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 2 0 0 8
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 organiza-
t 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 au-
thor, 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 ele-
ments. T h e 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 i n h e r i t their transforma-
tions and processing mechanisms,
reducing the development cost.
T h e D I T A Open TooIMt is a refer-
ence i m p l e m e n t a t i o n of the D I T A
specification developed by the Or-
ganization 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 trans-
forms 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).
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 prese-
lected 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
intercom
tools of the trade
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 every-
t 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 or-
ganization 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 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

iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiniiiiiiiiiiiiiiiiiiiii
««H*t««M«««»«««+*«**»AUT0**«5 - DIGIT 46268
112948 ICOA
MRS. PAULA N HARLOW 70378
7451 WINTON DR P309
INDIANAPOLIS IN 46268-5103