In this exclusive interview with TheContentWrangler.com, Patrick Willekens shares lessons learned, success factors, and recommendations for others who are thinking of making a move to the Darwin Information Typing Architecture (DITA).
TCW: Tell us a little bit about yourself, Patrick.
PW: I graduated in 1988 in Leuven (Belgium) as a civil engineer with masters in electronics and completed an MBA a couple of years later. I worked most of my life as a product manager. During the early 90s, I worked eight years for Mentor Graphics (chip design software sector). In 1997 I took a job with ICOS Vision Systems Corporation. At ICOS I am responsible for worldwide documentation and training management, in addition to my ongoing responsibility as product manager for a small product line. I manage a team of 3 technical writers and 1 test coordinator.
TCW: What is ICOS?
PW: ICOS Vision Systems Corporation NV (ICOS) is a Belgian public company and a leading world-wide developer and supplier of inspection equipment, primarily for use in the back-end semiconductor and the electronics assembly markets. ICOS manufactures and sells inspection systems for the semiconductor packaging industry and is market leader for inspection systems for the final outgoing visual control of chips, before they are used in various applications such as PC’s, cars, mobile telephones, digital cameras, flat panels, etc.
ICOS aims to be a long-term reliable partner to its customers by offering the latest innovations in technology and providing cost-effective, accurate and flexible solutions
TCW: Why did ICOS decide to adopt the Darwin Information Typing Architecture (DITA)?
PW: Until 2005 we were using MS Word as text editor. With an increasing amount of products and variants, we became more and more aware of the restrictions of this editing platform, mainly with respect to text re-use, translation management, print and web output and customer-specific manual generation. We knew we wanted to migrate to XML but the choice of DTD was not so clear. Initially, we wanted to use IMAP. We even took IMAP training, but we didn’t like the restrictive formatting of the resulting documentation. DocBook was ruled out almost immediately since we wanted to change from book-oriented to topic-oriented writing. In discussions with content management system (CMS) vendors we learned of DITA and immediately liked the concept. Despite the non-existence of official support in any CMS at that time, we decided to stick to our decision (and we’ve not regretted it).
TCW: What documentation (content) did ICOS use DITA to create?
PW: So far we have published 5 manuals:
- A Solar Cell Inspection Concise manual (61 pages) and Engineer manual (257 pages) in 20 different variants. Available in English and being translated into German.
- A Flex Tape Inspector Concise manual (135 pages) and Engineer manual (around 283 pages) in 3 different variants. Available in English and being translated into Japanese.
- A Component Inspector Engineer manual (249 to 280 pages depending on the variant) in 5 different variants. Available in English and being translated into Japanese.
We have also written all our ISO9000-2001 procedures (51 documents) in XML. The reason for this is to allow transparent management of changes in a CMS, uniform look-and-feel, and translation of procedures into local languages for our branches overseas.
There are many more manuals in the pipeline. Next in line is a service manual for the Flex Tape Inspector. At least 10 more manuals will be created using DITA this year.
TCW: Is any of this content available (can I point to it) on the web?
PW: Currently we publish to PDF only. Publishing to HTML is planned for the middle of this year but will be available in a password-protected environment only.
TCW: Did ICOS have to specialize (customize) DITA for its purposes? If so, what did you need to specialize and why?
PW: We have not done any topic or domain specialization. So far we can manage with the standard DITA DTD. We had to modify the DTD here and there (additional entities in the DTD files and some additions to topic.mod, map.mod), mainly to support conditional publishing and fancy features such as publishing a variant-specific picture on the front page.
TCW: How many writers were tasked with creating content using DITA? And, were the writers geographically dispersed?
PW: We have a small team of only 3 technical writers. They are all located in the same office, even in the same cubicle.
TCW: What content management tools did you use to help you manage the content and the writers tasked with creating DITA content? How are these tools helping you do things differently today that you could not do in the past?
TCW: What authoring tools did you use to implement? If so, what versions?
TCW: Did your authoring tool provide any additional functionality or support for DITA? If so, what?
PW: We decided not to upgrade to XMetaL DITA Edition for the time being. In my view, the additional DITA support is very valuable for people who are not using a CMS but does not bring sufficient additional value in combination with a CMS.
TCW: Why didn’t you just use Microsoft Word to create DITA content?
PW: Word is pretty useless for technical writers who want to write content in XML. You can indeed import an XML schema into Word and you can see your content with XML tags. But you don’t have features you need such as the WYSIWIG modeling, context-sensitive element display, attribute display, conditions support, etc.
TCW: What benefits did DITA provide ICOS over the old way of creating content?
PW: We would never have been able to create 20 different variants of one manual in a reasonable amount of time using Word. Also, we will be enjoying considerable cost savings in translation for the next versions of our manuals. And, customers like the topic-oriented approach since it allows easier browsing.
TCW: What lessons learned can you share with others interested in considering a move to DITA?
PW: The first manual will seem to take forever to complete, just because there are a zillion things that need to fit together to make a manual: the right granularity for your topics, where and how to put conditions in your text, layout issues with elements being used in different environments, getting the index built up, proper display of the images in your layout etc. Don’t get discouraged too quickly. Once the first manual is ready, the others come out in a breeze.
TCW: Can you think of any content types that would not lend themselves to DITA?
PW: I would only apply DITA for technical documentation. In this context users just want to know how to do a certain task and that’s it. There are virtually no users who read a manual front to back before they start using the system. They try something, stumble, curse and finally look it up in the manual. This is the great thing about DITA: the task is the most important building block, the concept is there for the interested reader who wants to know why as well and references are supporting both tasks and concepts by serving as a kind of encyclopedia with tables, schematics, diagrams etc. If you want to make something that is readable from page 1 to page 312, use DocBook (or stay away from XML).
TCW: Are there any issues with using DITA for print output?
PW: There is a finite set of elements that you can use. Each of these elements needs to have the proper representation however when used in print output in ALL circumstances. For example general elements such as a list can be used in many different situations and things like indentation need reviewed, carefully. We have spent weeks getting the PDF output just right.
TCW: How much content (%) were you able to reuse?
PW: So far the reuse is limited since we are now creating first-of-a-kind documents. We have multiple product lines, each with their own products. Soon we will make a manual for the rev2 version of a machine for which a rev1 version manual already exists. Then we will start seeing real reuse benefits. I estimate that 80% of the topics will be exactly the same for the rev2 manual. In MS Word we used to make a copy of the rev1 manual and started reading from page 1 to the last page, making changes here and there. We will now know exactly which topics to edit and which topics will stay exactly the same. This will make the editing a lot quicker and transparent.
TCW: How did DITA help with translation?
PW: It is not so much DITA that helped us but the SiberSafe CMS did. SiberSafe lets us create an exact linked copy of the original manual, replace the images by the translated versions (while keeping the original xrefs) and will only allow us to change the content of the elements. Content creators cannot remove or add elements. This assures a one-to-one equivalency between the original and translated content. When updated content appears in the original content, the translated content for each changed element will switch back to the original language so the translation office will immediately find the changed content.
TCW: Did writers have any difficulties or issues using DITA? If so, what were some of the common ones?
PW: We started with no knowledge about XML and no knowledge about DITA. It was not easy to ramp up our knowledge. While all of our technical writers have engineering degrees, an e-learning course on DITA would have been nice. I would not recommend going to DITA without an engineering background or at least an affection for technology.
The biggest hurdle in the beginning is the fact that there are many elements that you can use on a given position. Each element needs to be chosen from a cryptic acronym. You have to lookup in the language reference manual what this acronym stands for before you know if you can use it and how. XML authoring tools should provide for a pop-up help when you move your cursor over these elements.
The second hurdle was the use of conditions in our text. We had to define attributes for that, put these in entities and embed these entities in our DTD. This was quite a learning process as well, especially since the support for conditions in DITA is not what it’s supposed to be when you have many conditions. We try to model the complete machine that we describe with conditions in our source text: all options are non-exclusive conditions; all software versions, machine revisions, target audience etc are exclusive conditions.
TCW: What challenges did you encounter?
PW: The management of all these conditions in our source text is giving us quite some headaches. Especially since the DITA behavior is quite surprising sometimes: “Include by default; if excluded, then remove, but if included explicitly then ignore any exclusion.” Try to figure this out when combining many conditions. It often leads to surprises.
TCW: Does ICOS plan to use DITA for other projects?
PW: All our documentation projects will be done in DITA, both for paper (PDF) as for web-based help. No extensions are planned to other domains such as marketing. The topic-based architecture is not really applicable to those domains.
TCW: What advise can you share with others who are considering DITA, but aren’t sure it’s right for them?
PW: Try to make a topic map of your documentation set. Rethink your complete manual in concept, task and reference topics (one rectangle box per topic) and indicate the links between all these topics with arrows. If you cannot complete this exercise on paper, don’t go to DITA.
TCW: Is it possible to move to DITA and really mess things up?
PW: I don’t think you can really mess up your documentation if you use an “intelligent” XML editor which prevents you from writing incorrect XML. The only thing you need to be careful about is how you want to present your documentation to the outside world. We spent far more time in generating decent PDF then in migrating our content into DITA. When you are used to working in Word you want to tweek the layout until it feels just right. This is not possible when you work in XML and layout considerations are a very important topic in your migration path.
TCW: If you had a DITA wish list, what functionality would you add to DITA and why?
PW: There are 2 items on our wish list:
- Better support for conditions by allowing wildcards (see above)
- Support of the SVG format in DITA reference topics. We need to create complex service manuals including schematical and pneumatical diagrams. It is not possible to publish them on one page so we need to be able to generate html that calls SVG objects and allows us to zoom, search, pan through these objects.