February meeting of Boston DITA Users Group

Last week's Boston DITA User Group meeting featured Judy Kessler, the
DITA Transition Lead at Sybase.

Her topic was Making the Business Case for DITA.  Attendees were all
very interested and kept Judy overtime (our longest meeting to date).

She said her presentation reuses material from earlier
presentations justifying DITA, both inside and outside Sybase
(IBM for example) and encourages others to follow
this example. You will need the very best arguments.

Sybase's DITA strategy is a long-term strategy - three years or longer! Don't assume you can get it done in one release cycle.

You must identify the role of technical publications in your company.

What does the company do with pubs? Who does the work?  Who are the leaders? They will be key stakeholders. Major stakeholders outside tech pubs include internal and external stakeholders.

Internal stakeholders include: technical development team (engineers, QA), customer-facing technical team (tech support, tech sales and consulting), product marketing, program managers (who coordinate processes, release timelines, pricing, localization, etc.), the globalization team (they contract this out), and executives (who are bottom line number oriented, but can be sold on better and faster docs from the existing team).

External stakeholders are end users - customers, clients, partners,
etc. Sybase has a strong focus on user-centered design. Documents are
written for those who read them and use them. They have multiple levels of users, so docs need to be targeted for beginners vs. experienced, and for
different cultures (e.g., many Asian users still look first for a full
conceptual understanding rather than just contextual help).

At Sybase, the move to adopt DITA began within the tech pubs
management team. It has a director, managers, team leads and project

You can probably assume the director already believes in basic
documentation objectives like consistent look and feel, repurposing material rather than rewriting, and multichannel output (web, print, etc.)  They may know the answer is to have more granular material. But don't assume they know exactly how to do it. They need to be convinced about DITA and become the business driver (in-house product champion).

The first step then is to send your tech pubs director to a
conference/workshop on DITA and topic-based writing. Several members of the Sybase documentation management team have attended JoAnn Hackos conferences and recommend them highly.

Next is a survey of tools currently in use for three stages in the
environment - authoring, processing/production methods, and delivery. Sybase found authoring tools used were Word, Framemaker+SGML, RoboHelp, and XML editors for DocBook-based, topic-oriented Help.

Production included several internally developed, OmniMark-based
scripts. Delivery channels included HTML, PDF, JavaHelp,
EclipseHelp, ...

Issues they found with the current environment were pressures to do
more work with equal or less resources. The assumption was that once over the transition they could get better quality documentation with the
same number of contributors.

A requirements analysis included: RAD (rapid application development)
has led to more products with shorter release cycles, products with
merging feature sets, increased number of output types, parallel
development of products and documentation, increased efficiency (fewer writers per project), increased effectiveness and user satisfaction, and the delivery of product suites rather than point products.

Merging product lines easily had a great appeal for management,
especially because they have done several acquisitions. A
documentation system based on standards makes it easier for tech pubs to incorporate content from acquisitions and evolving products.

Sybase considered having all the writers trained by a custom workshop, but it proved too expensive. Instead, it adopted a train-the-trainer approach.

Writers are trained in how to write reusable topic-based material.
In addition, they are cross-trained on other Sybase product lines.
Another reason is that so many products are merging into
integrated product suites. Some features from product A are being included and others from Product B. Chunking the docs makes this kind of integration possible. Judy said that focusing on changes like this in your business should be the biggest take away for attendees.

The final benefits slides for Making the Business Case included the
popular Why DITA bullets we have seen from IBM, plus a very important
slide she called Industry Momentum which improved the top management's comfort level. It lists some major companies moving to DITA. It concludes with a quote from JoAnn Hackos - "We believe that DITA represents a new standard..."

After completing the Business Case, Judy discussed the work in progress
and showed the Sybase adoption schedule.

The new environment replaces all authoring tools with just one, XMetaL
Author, DITA Edition. A single new processing/production approach is
being developed by Sybase. It will be able to deliver all the current output channels, plus some new ones.

Some legacy document conversion is being outsourced, but most is being
done in-house. An unstructured Framemaker doc set is being converted to DITA by a local conversion services firm. Word document conversion is being done in France by a member of the team that writes those docs. If your firm has people with appropriate scripting skills, you might take on some of these conversions in house. They wrote their own conversion scripts for documents already structured.

The new author training is a five-day workshop. On or before the first day they get their tools environment set up. They get two books, the "Red Book" (Introduction to DITA, from ComTech Services, by Linton & Bruski) and IBM's Developing Quality Technical Information: A Handbook for Writers and Editors.
[Ed. note: I would add JoAnn Hackos' new version of her 1994 classic "Managing Your Documentation Projects, now called Information Development.]

The second day is spent on topic-based writing, task analysis and content analysis. Only on the third day do they get to the tools. A lot of the discussion is about roles. Who will do what? What's an IA (information architect) Can I be the IA?, etc.

They then learn to develop topics, maps, relationship tables, etc. They
study the style guide - what to name files, where to put them, etc.
For now they manage map and other file locations from a spreadsheet (about one computer screen does it).

Judy's slides are attached (Powerpoint PDF)

Bob Doyle

We also discussed the latest version of the new DITA Users website, now offering online editing of DITA files and processing through an online version of the DITA Open Toolkit. Beta testers are welcome to join DITA Users now.

Sybase_DITA_Bus_Case.pdf953.67 KB
XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I