DITA: A Universal Solution?
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015Words: 9,848AbstractDuring the last few years, DITA has spread in many companies and sectors and is oftenconsidered as the “must have” tool for technical writing thanks to its flexibility andadaptability. However, does DITA really live up to its reputation?We start with noting that the concept of DITA was designed to serve this purpose. We thentry to learn more about DITA and its implementation through webinars, specialized articles,surveys about DITA, and especially one that we conducted from March to May 2015. Wecame to two main conclusions.First, financially speaking, DITA remains relatively affordable for larger or smaller companies,as long as they are not looking into specialization, and provided that the implementation planis complete and fully backed by management. In addition, the productivity gains they getfrom transitioning to DITA are mainly determined by the implication of companies and thecontext of the implementation.Secondly, DITA is not restricted to the software sector. It brings a lot to a wide variety ofdomains thanks to its universal benefits: content reuse, its linking system, the expansion ofelectronic documentation and the possibility to be specialized. Besides, even though DITA isfor now mostly used by documentation teams composed of professional technical writers,LightWeight DITA seems to be quite promising in improving the spread of DITA outside thedocumentation departments.Key Words: DITA, Universal, DITA Implementation, Productivity, Domain of Activity,Paper-Based Documentation, Electronic Documentation, Content Reuse, Linking System,Company Size, Topic-based Writing
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015IntroductionWhen studying technical writing, authoring in DITA has become an unavoidable course.Nowadays, more and more companies use DITA and it is thus very convenient for them to hiretechnical writers already trained to the DITA standard.When we started our apprenticeship, some of us were immediately immersed in a DITAenvironment while others worked with different documentation tools. The origins of thisresearch stem from these different professional environments: two business contexts (GE Healthcare and Dassault Systèmes) two types of documentation (paper-based and electronic) two types of product (software and hardware) three writing methods: One member is working with unstructured FrameMaker (in the process ofmigrating to DITA). Another is writing in structured XML (in the process of migrating to DITA). Two members are writing with XML DITA.Thus, our questioning around structured writing started from these very distinct writingmethods. We wondered why some companies decide to migrate to DITA, why others havemigrated and finally what kind of companies are interested in the migration.More widely, we noted that DITA has invaded the technical writing world over the last fewyears, and that it was often considered to be at the cutting edge of technology and thedreamed solution for all types of documentation. But does DITA really live up to its reputation?Is DITA really universal?In this article, we will first consider the origins of DITA, and we will especially show that DITAwas designed to be universal. Then, we will focus on the facts about DITA and itsimplementation: we will present the results of a survey we conducted from March to May 2015and describe the current situation of DITA, making explicit the types of sectors and companiesin which it is used. Finally, we will analyze more precisely these data by examining the financialaspects of DITA on the one hand and, on the other hand, the possibilities to adapt DITA to all2/32
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015sectors, to all types of documentation, and, why not, to use it also outside the documentationdepartments.DITA: The OriginsThe concept of DITA was developed by IBM Software & Services in the early 2000s for itsinternal documentation “as an alternative XML-based documentation system, designed toexploit XML as its encoding format” (Priestley and Schell, 2005). The company wanted toreplace its existing and very complex SGML DTD, called IBMIDDoc. The workgroup in charge ofthis task finally came to the ideas of topic types that are gathered in maps and of specialization.In 2005, IBM donated this material to the Organization for the Advancement of StructuredInformation Standards (OASIS) to release it to the public. In fact, IBM realized that it “would bemore useful if [it] could actually have this spread to other firms that [it was] dealing with, othervendors, other suppliers, so that they could then have a common format for all thedocumentation and be able to share treatings back and forth and in a common XML basedformat” (Schengili-Roberts, June 2015). The concept became a standard and DITA 1.0 appearedin June of the same year.The acronym DITA stands for “Darwin Information Typing Architecture” which describesprecisely the concept of DITA. The core element is “architecture” since the aim of DITA is toprovide a new way of structuring information. DITA is based on an XML document typedefinition (DTD) called “the topic DTD” that was designed “to support many products, brands,companies, styles, and delivery methods” (Priestley and Schell, 2005). DITA, as a UserAssistance Development Director at Dassault Systèmes explains, appears as a natural evolutionof documentation authoring, from the unstructured to the most structured authoring: from asimple text document to the use of FrameMaker, then HTML that becomes XML, which finallyleads to DITA.DITA is a relatively recent tool that was originally created for electronic documentation so it iswell adapted to this type of format. This comes at a moment when electronic documentation isexpanding and replacing printed documentation. Electronic documentation is easier to manageby technical writers and findability is improved for users. Printed documents not only need tobe stocked, occupy space and are cumbersome, but the content is also static, knowledge is lostand content reuse is difficult. DITA certainly benefited from this expansion of electronicdocumentation, which may explain its success.This global context, and the environment in which the concept of DITA was developed, that is ina software company, favored the spreading of DITA in this sector. The early DITA adopters wereeither software firms, such as Adobe, or companies that had a software component, like for3/32
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015example Nokia or Blackberry (Schengili-Roberts, June 2015). In fact, programmers were alreadyfamiliar with that kind of tools and they found in DITA some aspects that were similar to theirway of working.Indeed, “the Control Version Systems (CVS) used for software development could also be usedfor DITA content” (Schengili-Roberts, June 2015). Programmers already worked with a CVS thatallowed them to update a file without losing the previous version of the file. At any moment,they could get back to one of the numerous versions that were saved. Thanks to that tool,when they created a new component for a product and did something incorrect or wrong thatthey had to revert, they could get back to a previous version of their work. Similarly, with DITA,all the versions of a topic are available at any moment and it is easy to go back to a previoustopic version. In addition, DITA was considered to manage object-oriented content which waslinked to the idea of content reuse, a well-known concept for programmers: they “[realized]immediately some of the possibilities of such a system” (Schengili-Roberts, June 2015). Insoftware firms, employees have the perfect background to understand the way DITA works,and they feel familiar with this system.At the beginning, DITA was thus mostly used in software technical documentation departments.However, DITA developers wanted to create a concept that could be used by a majority offirms, in the software domain as well as in the industry sector. To achieve this goal, they tried tomake DITA as flexible and adaptable as possible. The main topic types (task, concept, reference)are thought to be relevant for all document types and their fine granularity allows infinitepossibilities of combinations and linking systems that are established in maps. A topic canappear in many deliverables and when it is updated, the changes are set in all of them. Oneexpert in technical writing we interviewed emphasized these aspects when comparing XML usewith Arbortext and DITA: “The previous template was incomplete and DITA offered morepossibilities with relationship tables, DITA maps and the ability to reuse content” (ourtranslation).DITA was intended to be large enough to take into account as many needs of a wide range offirms as possible, and in that sense to be flexible. But DITA is also adaptable since a companycan integrate some particular features, specific to the company, in its own DTD especiallythanks to specialization. The DTD is composed of a basis that is common to all DITA users andthis basis can be expanded according to the firms. A French leading company in 3D software,for instance, has added some elements to its DTD so that it matches the needs of the company.A series of elements to create interactive tutorials has been created, in particular elements tointegrate the script in a task, and concerning tooltips, dl has been defined so as not to allowuseless information such as a list title or a table in a dd .4/32
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015A User Assistance Development Senior Manager in this French company underlines that theadvantage of DITA semantic markups (specialized if needed), is that writers focus more on thecontent they are authoring than the final layout. For instance, for them the uicontrol tagsresult in bold characters in the published file: technical writers now use uicontrol for allelements enabling users to control the user interface, and do not use bold tags anymorewhich do not have other meanings than formatting ones. The differences in font weight or styleare meaningful, they represent specific units of information that need to be emphasized, andthey are not just an esthetic problem. There must be a reflection to categorize what is to beauthored, and technical writers do not have to be preoccupied by layout problems, which cannecessitate a lot of time and distract them from content.As far as the user is concerned, the User Assistance Development Senior Manager weinterviewed mentions that “the goal of DITA is to improve the user experience. [In our companythey] are not looking for advantages that would impact the technical writer, but what it bringsto the user” (our translation). DITA is, according to her, one of the best tools to improve userexperience because thanks to the electronic medium, topic types, DITA maps and the linkingsystem, the user is able to retrieve information faster.What served DITA developers in their wish to spread their concept to as many firms as possibleis that the technical writers who worked in companies that adopted DITA as soon as it wasreleased brought their knowledge of DITA to other firms when they changed jobs. Now DITA iswell-known and is more and more used by companies because it is a standard, and it isconsidered to be a modern tool for authoring. When a company uses obsolete tools for itsdocumentation and decides to invest in new tools and a better organization, it will start withconsidering the DITA option. In addition, there are specialists of DITA that have consulting firmsthat help companies to adopt DITA: they estimate costs, prepare the migration, and organizethe training of technical writers (Schengili-Roberts, June 2015). However, in some companiesthe choice of DITA is sometimes imposed, especially for small firms that have been taken overby bigger structures. A technical writer we questioned explained us that for his company “it wasa corporate necessity because [it] was acquired by [an American multinational firm]and [they]were obliged to align with [its] tools and practices.”Even though DITA was created 15 years ago with the purpose to satisfy a wide range ofcompanies, it was at the beginning almost exclusively used by software firms or at least firmsdeveloping software components. Things have changed over the past few years, and it is nowinteresting to focus more closely on the expansion of DITA and the type of companies andsectors where this standard is used.5/32
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015DITA: The FactsFigures and facts about DITA are important to analyze in order to get an objective point of viewon the whole subject. Even though we found surveys presenting different fact informationabout DITA and we all work in companies and documentation teams with a different experienceof DITA, it immediately appeared necessary to go beyond these business contexts and to collectthe thoughts of experts from different sectors and companies in order to have a more neutraland complete viewpoint. We thus decided to conduct a survey, summarizing all the questionswe had about DITA implementation into a form. This survey was posted on thebusiness-oriented social network LinkedIn (on the “DITA in France” discussion group), andemailed to 23 technical writers working for various companies. We also interviewed the SeniorTechnical Writer who is in charge of documentation architecture, structure and toolsmanagement at Dassault Systèmes and who managed the Frontpage to DITA migrationbetween 2008 and 2011.The form was split into three sections, each corresponding to a different experience of DITA.We asked respondents to fill in the section that corresponded to their own experience : The first section was dedicated to technical writers or information architects whocurrently write non-structured or non-DITA content. The questions were:Would you like to migrate to DITA? Why? Does your company intend to migrate toDITA? Why? The second section was dedicated to technical writers or information architects whohave experienced a DITA migration. The questions were about the different stages ofthe migration process: Information background on DITA migration in the company: When did themigration start? When did it end? What was your position during this migration?Before migrating to DITA, what authoring tools were used in your company? Reactions to DITA migration: If you were working for the company at this time,how did you react when you were informed of the migration? Have you or yourcompany experienced any technical difficulty? If so, can you be more specific?Have your writing habits been challenged? If so, can you be more specific? Haveyou or your company faced behavioral challenges? If so, can you be morespecific? After the migration: Has your company produced an evaluation report after themigration was completed? If so, on which criteria was this report based and6/32
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015what conclusions were drawn from this report? According to you, what benefitsdid the authors and your company get from this DITA migration? Do you haveany reservation about this migration or about DITA in general? If so, can you bemore specific? The third section was dedicated to technical writers or information architects whocurrently write in DITA but have never experienced a DITA migration. The questionswere: Have you ever worked in other authoring environments that were non-DITA? Ifso, can you be more specific? From the writer’s point of view, what are the positiveand/or negative points of DITA? According to you, what are the positive and/or negativepoints of DITA for your company?All respondents also had the possibility to add further comments, experiences, ideas orthoughts at the end of the survey.The limits of this survey were also parts of its strengths: spreading it on discussion groups orsocial networking services reduces the possibility to establish a precise number of sent formsand some members of the discussion group directly answered in a comment to our post ratherthan following the provided questions in the form. However, it enabled us to reach moretechnical writers who would not have filled in the form and to get information like useful linksand readings we would probably never had without this possibility of direct comments.21 respondents filled in the form and we got 18 relevant testimonies. We obtained thefollowing results in terms of numbers:Figure 1: DITA Usage Among the Respondents7/32
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015According to our survey, the software industry is more attracted to the DITA standard (seeFigure 2).Figure 2: DITA Usage by Industry Sector Among Our RespondentsRespondents whose companies had migrated to DITA reported that this migration was carriedout between 2008 and 2014. For those who have implemented DITA, the migration took onaverage 1 to 4 years, depending on the size of the company.Ten of the respondents who are already using DITA or currently migrating to DITA are workingin multinational companies with a minimum of 500 employees, a gross turnover superior to onebillion euros and large documentation departments. Only 2 of our respondents using DITA areknown to be working in small or medium-sized companies. It seems that there are moremultinational companies using DITA than small or medium-sized ones (see Figure 3).8/32
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015Figure 3: DITA Distribution by Company SizeTo the question “Would you like to migrate to DITA?”, most of the concerned respondents gavea negative response that reveals reluctance (see Figure 4).Figure 4: Number of People Willing to Migrate to DITAThis survey enabled us to better understand the subject through a wide range of experiencesand provided us the information we needed to properly analyze the question of the universalityof DITA.9/32
DITA: A Universal Solution?Marion L., Catherine S., Jean-Michel V.D.B., Laureen Z.Paris Diderot UniversityJuly 2015On the one hand, we collected important accounts from professionals (colleagues, tutors,other), but they remain personal and subjective. On the other hand, our survey mainly gatheredpartial collections of facts and opinions but no figures. To complete our analysis, we turned tospecialized articles, newsletters and surveys conducted and written by experts. We alsofollowed two webinars in line with our questions: one was presented by Leigh White, aspecialist in DITA documentation at Ixiasoft, and the other by Keith Schengili-Roberts, a DITAinformation architect. These resources helped us to determine what kind of companies useDITA in terms of domain, size, turnover and so on.In 2013, Keith Schengili-Roberts conducted a survey called “Who is Using DITA and Where is itBeing Used?” published in the CIDM (Center for Information-Development Management)newsletter Best Practices . He collected information from conferences listings, emailing andcustomer references in order to know which companies are using DITA to produce theirtechnical documentation. This survey shows that “400 firms have been identified as using thedocumentation standard. Undoubtedly there are more firms out there waiting to bediscovered.” According to a 2015 survey (see Figure 5), DITA usage has increased and there areapparentl
LightWeight DITA seems to be quite promising in improving the spread of DITA outside the . Introduction When studying technical writing, authoring in DITA has become an unavoidable course. . (OASIS) to release it to the public. In fact, IBM realized that it “would be more useful if [it] could actually have this spread to other firms that .
The DITA Open Toolkit (DITA-OT) is an open-source implementation of the OASIS DITA specification, which is developed by the OASIS DITA Technical Committee. The DITA-OT is a set of Java-based, open-source tools and Ant scripts that transform DITA content (maps and topics) into deliverable f
DITA technologist should read, not the average writer or manager. The good news is that we’ve designed DITA 101 for writers and managers. We’ve taken our years of expe rience helping organizations to move to DITA a
According to the DITA Exchange product team, the map viewer is the most frequently accessed UI by SMEs and serves as a popular entryway into topic creation, review, and revision. Technically, the map viewer is not part of the DITA Exchange editor, rather it is part of DITA Exchange’s l
OASIS Darwin Information Typing Architecture (DITA) TC Chair(s): Don Day Editor(s): Michael Priestley Robert D. Anderson JoAnn Hackos Related Work: This specification replaces or supercedes: OASIS DITA Language Specification Version 1.0 This specification is related to: OASIS DITA Architectural S
DITA Architectural Specification v1.0 1.1 approved as an OASIS Standard in August 2007. DITA Language Reference v1.1 DITA Architectural Specification v1.1 1.2 approved as an OASIS Standard in December 2010. DITA Specification v1.2 Current version of
Man y DITA authoring and publishing tools come with standard transformers for most common delivery formats, such as PDF, RTF and HTML. The DITA Open Toolkit, an open source collection of utilities and documentation to help writers work with DITA, includes basic transformers for PDF, RTF, HTML, DocBook, Eclipse Help, and Microsoft HTML Help.
Member OASIS DITA Technical Committee, Lightweight DITA Subcommittee, co-editor OASIS Lightweight DITA Committee Note Adjunct Instructor, Carnegie Mellon University. This Month in STC Roundtable . Modern Technical Writing: An Introduction to Software Documentation, Andrew Etter
Abstract—Agile Software Development (ASD) has been on mainstream through methodologies such as XP and Scrum enabling them to be applied in the development of complex and reliable software systems. This paper is the end result of the Master’s dissertation of the main author, and proposes a solution to guide the development of complex systems based on components by adding exceptional .
