Adobe Systems Speaks Out on DITA: Internal use of FrameMaker, CMS, and DITA

by Kay Whatley (Ethier) and Scott Abel

Interview with Puny Sen

Project Lead, Instructional Communications, Adobe Systems

Bright Path Solutions asked Puny Sen, Project Lead, Instructional Communications at Adobe Systems to talk about the software giant's foray into the world of the Darwin Information Typing Architecture (DITA). Sen shares details about Adobe's recent DITA documentation project, the pro's and con's of using DITA with FrameMaker, as well as lessons learned of importance to anyone interested in adopting the DITA standard.

BPS: Puny, tell us a little about yourself.

PS: I've been an XML consultant for the last five years, focusing on XML repositories, content management systems, middleware, business processes and web-site design using XML. For the last one and a half years, I've been the information architect for Instructional Communications at Adobe, responsible for converting legacy content to DITA, implementing a content management system, and writing transformations for our various outputs.

BPS: Why did Adobe Systems decide to adopt DITA?

PS: The notion of a "Product Suite" meant there was considerable shared functionality. By adopting a topic-based schema, we could ensure these common features were authored once and shared amongst the different suites.

BPS: What documentation (content) did Adobe use DITA to create?

PS: User Guides for all of Creative Suite 2 (InDesign, InCopy, GoLive, Photoshop, Illustrator), as well as Adobe Photoshop Elements version 4.0 and Adobe Premiere Elements 2.0.

BPS: Is any of this content available (can I point to it) on the web?

PS: Not at the moment.

The content created with DITA is shipped with the product

BPS: Did Adobe have to specialize (customize) DITA for its purposes? If so, what did you need to specialize and why?

PS: Yes. Specializations were needed to cater for things such as:

BPS: What lessons learned can you share with readers about specializing DITA?

PS: Specializing is a complex issue. Specialization is one of the best things about DITA and one of the least understood. Specifically, topic specialization and domain specialization can be especially challenging.

Topic specialization is needed when you need to create a new type of topic. The basic topic types that come with DITA are sufficient for the majority of the documentation we create, but not all.

Domain specialization allows you to specialize elements at the sub-topic level and use the specialized element and use it in the same context.

We created versions of those elements that we needed for our purposes. The PH element is a phrase element - for instance, we could use this to create variables - or special types of conditions. What we did was create an Adobe domain where we put our specialized elements.

Domain specialization has a lot of other uses (industry specific, etc.) and you can create your own new domain that provides a huge opportunity for collaboration. I can see a lot more domains springing up in the future.

Understanding specialization is hard because it is a new concept for many writers and it is also hard to implement because it is very prone to errors (manipulating the DTD correctly). Specialization requires a lot of discipline.

It would be great if there were some specialization "wizards" to help you correctly implement the DTD changes that are needed when you specialize DITA. And it would help us all to conceptualize what specialization is and how it works.

BPS: How many writers were tasked with creating content using DITA?

PS: There were about 20 writers.

BPS: Were the writers geographically dispersed?

PS: Yes they were geographically dispersed - mostly in Seattle, San Jose, and Indiana.

BPS: What content management tools did you use to help you manage the content and the writers tasked with creating DITA content?

PS: We used a content management system - WorldServer Global Electronic Publishing, from Idiom Technologies Inc. -- which distributed the structured application files to each writer's machine. Artwork was (optionally) mapped via a WebDAV client (WebDrive).

The XML files were stored in an XML Repository (Xhive) and accessed through GEP. When an author was working on a document, it was automatically checked out and locked by the CMS.

BPS: Were there any performance issues with that approach?

PS: There were no serious performance issues.

BPS: What software tool did you use to implement DITA (did you use FrameMaker)? If so, what version?

PS: We used Framemaker 7.1

BPS: I'm assuming FrameMaker 7.2 was not ready when you started the project. Are you going to use FrameMaker 7.2 moving forward?

PS: We're planning to migrate to 7.2 in the near future.

BPS: Does FrameMaker 7.2 provide any additional functionality that will help those who aim to use DITA? If so, what?

PS: FrameMaker 7.2 comes with a DITA starter application. But that is by no means enough to help people to understand the concepts behind DITA. What we need is a way to teach people to understand and use DITA within FrameMaker.

7.2 also has some great capabilities to style documents. It will help get rid of read/write rules that are always a challenge for FrameMaker users.

BPS: What benefits did DITA provide Adobe over the old way of creating content?

PS: Content validity. We only allowed content to be uploaded and checked in if it was valid. We were also able to enforce editorial rules.

BPS: What editorial rules made content valid? Give me an example.

PS: DITA by itself can help you enforce some editorial rules. For instance, a task has to be formatted a certain way. What people need to realize is that DITA is still very flexible and needs to be constrained so you can get consistency in documentation.

At Adobe, we had to constrain DITA so it would not allow authors to do thing we did not want them to be able to do. For instance, we did not want authors to be able to insert consecutive bulleted lists (DITA allows that). To address that issue that, we had to create a rule that would prevent DITA from allowing an ordered list from being followed by another ordered list. In our experience, we saw no need for consecutive lists, so we had to develop a way to prevent that situation from occurring.

We also are still trying to address some other issues. For instance, DITA allows authors to insert block elements (lists or figures) inside of paragraphs. While that doesn't seem problematic on its face, DITA also allows authors to insert block elements of a paragraph, which causes consistency problems because authors are able take different approaches.

BPS: What other benefits did DITA provide Adobe over the old way of creating content?

PS: DITA made it possible to insert cross-product cross-references.

BPS: What are cross-product-cross-references?

PS: Cross-product cross-references are a cross-ref...for example, a reference from Photoshop content to Illustrator content. In a book paradigm that wouldn't work, but in XML cross-reference targets can be anywhere. DITA and XML help us avoid being by the paradigm of the book.

BPS: Adobe also enjoyed other benefits.

PS: Yes, we were able to focus on creating content, not formatting it.

Authors did not have to worry about formatting and could concentrate on the structure of the content instead. Additionally, the schema served as a guide to authors on what to enter next.

Content re-use meant less maintenance. Authors could place content references to shared topics instead of copying and pasting them into different locations.

Consistent output was a big benefit. We could build the same output at the click of a button. There was no desktop publishing work needed.

And, we were able to use XQuery to run powerful searches across the content. It was easy to write reports to check for missing images, broken cross-references, erroneous index terms, etc.

BPS: What "lessons learned" can you share with others interested in considering a move to DITA?

PS: Be prepared to adapt DITA to your information architecture. Although DITA provides an excellent schema, it is necessary to think about things such as conditionality requirements (DITA does not allow extra conditional attributes to be added).

BPS: Can you give me an example of why conditions were a problem when using DITA?

PS: DITA has a default set of conditions, but as soon as you need another type of condition you are pretty much stuck. For instance we wanted to say this element is only appropriate for multi-byte languages (Japanese, for example). If we added an extra conditional attribute to an element it breaks DITA. DITA doesn't allow you to add attributes (extend them). It's a very contentious issue and a lot of people are working on it. But, there are a variety of suggestions for improving this. We'll have to see what happens.

BPS: What other lessons learned can you share?

PS: Before tackling DITA it is necessary to think about additional constraints that need to be enforced including:

And, you've got to think about content granularity - moving to the topic level may be an impractical first step. Especially since map editors are not mature yet.

Additional issues include recognizing that moving from unstructured Framemaker to structured FrameMaker is a formidable task. In the unstructured files, authors need to ensure that the correct paragraph styles and character formats are used (often, they are not). All overrides need to be removed. Consistency of structure needs to be enforced.

Framemaker conversion tables are powerful tools, but some XSLT post processing of your files may be necessary.

And, keep in mind that it's difficult to reliably convert conditions to attributes and cross-references may become flattened during conversion.

BPS: Are there any issues with using DITA for print output?

PS: Although the standard DITA transforms are great for online content, producing quality print output requires a lot of custom work.

We used FrameMaker Server to produce our PDFs. This provided a lot of benefits over XSL-FO including:

BPS: How much content (%) were you able to reuse?

PS: We estimate about 25% of content was reused.

BPS: Was the content created using DITA translated?

PS: Yes. We translated into 14 languages, including French, German, Spanish, Italian, Swedish, Dutch, Japanese, Chinese Traditional, Chinese Simplified, Korean.

BPS: How did DITA help with translation?

PS: We were able to use the translate attribute to filter content that did not need to be translated. By translating just the content and not the accompanying structure, we were able to ensure consistent formatting and presentation across all the locales.

BPS: Wow. Did writers have any difficulties or issues using DITA? If so, what were some of the common ones?

PS: The difficulties were mainly getting used to structured Framemaker and being restricted by structure. This becomes progressively easier, and most authors began to like being guided by the structure, rather than being restricted by it, and not having to worry about presentation.

Additionally, most authors found the DITA vocabulary intuitive and easy to learn.

BPS: Did writers need help determining why content was invalid?

PS: Authors are not allowed to upload content to the CMS unless it is valid. Since it isn't always easy to ascertain the reason why a document is invalid, extra support was occasionally needed.

BPS: What other challenges did you encounter?

PS: There were additional problems imposed by our content management system (not DITA), such as the ability to only edit 1 file at a time and not being able to easily copy and paste topics between files. These issues are being resolved as the system matures.

BPS: Does Adobe plan to use DITA for other projects?

PS: Yes. We plan to move content into DITA as new versions of products ship.

For the Rest of the Story