Optimising reuse with DITA XML: A case study of evaluating reuse strategies in DITA-authored documentation

Abstract

The utilisation of Darwin Information Typing Architecture (DITA) in technical documentation has become popular, and one reason for the popularity is its capacity for content reuse. This thesis explores various reuse strategies that using DITA as a documentation method offers, and how these strategies should be implemented in order to create reusable content. The theoretical framework of this thesis consists of single-sourcing, modularity, DITA, and reusability. Drawing from literature and previous studies, in this study I list reuse strategies that are then used when analysing the data. A combination of qualitative content analysis, theory-guided content analysis, and quantitative methods was used as a method in this study. This combination proved effective, and it provided a broad perspective of the current state of the reusability of the documentation. The thesis is a case study that was conducted for a large telecommunication company that produces complex network products. The customer documentation in the company is written in DITA XML. The research data consists of DITA XML topics and maps collected from the customer documentation of a specific product. The product’s documentation is authored by multiple technical writers. The analysis revealed both strengths and areas that require refactoring and improvement. Key findings emphasise the importance of standardised naming conventions, consistent terminology, and clear structuring for topics and DITA maps to enhance reusability and maintainability of the documentation. Additionally, a reusability checklist was developed which includes key characteristics essential for evaluating documentation content from a reuse perspective. This thesis contributes to advancing the understanding of documentation structuring and refactoring needs for enhancing the reusability of DITA-authored documents. The findings serve as a valuable resource for documentation teams that aim to create more consistent and reusable documents.

Darwin Information Typing Architecturen (DITA) hyödyntäminen teknisessä dokumentaatiossa on kerännyt suosiota, ja yksi syy suosioon on sen mahdollistama sisällön uudelleenkäyttö. Tässä opinnäytetyössä tutkitaan erilaisia uudelleenkäyttöstrategioita, joita DITA:n käyttäminen dokumentaatiomenetelmänä tarjoaa ja miten nämä strategiat tulisi toteuttaa uudelleenkäytettävän sisällön luomiseksi. Tämän opinnäytetyön teoreettinen viitekehys koostuu yksilähteistämisestä, modulaarisuudesta, DITA:sta ja uudelleenkäytettävyydestä. Kirjallisuudesta ja aiemmista tutkimuksista ammentaen luettelen tässä tutkimuksessa uudelleenkäyttöstrategioita, joita sitten käytän aineiston analyysissa. Tässä tutkimuksessa käytän menetelmänä laadullisen, teoriaohjatun sisällönanalyysinkvalitatiivisen sisältöanalyysin ja kvantitatiivisten menetelmien yhdistelmää. Tämä yhdistelmä osoittautui tehokkaaksi, ja se tarjosi laajan kuvan dokumentaation uudelleenkäytettävyyden nykytilasta kohdeorganisaatiossa. Tämä opinnäytetyö on tapaustutkimus, joka tehtiin suurelle tietoliikenneyhtiölle, joka tuottaa monimutkaisia verkkotuotteita. Yrityksen asiakasdokumentaatio on kirjoitettu DITA XML:llä. Tutkimusaineisto koostuu yhden tuotteen asiakasdokumentaatiosta kerätyistä DITA XML -topiikeista ja mapeista. Tuotteen dokumentaatiota kirjoittavat useat tekniset kirjoittajat. Analyysi paljasti sekä vahvuuksia että alueita, jotka vaativat refaktorointia. Keskeisissä havainnoissa korostetaan standardoitujen nimeämiskäytäntöjen, johdonmukaisen terminologian sekä topiceiden ja DITA-mappien selkeän jäsentämisen merkitystä dokumentaation uudelleenkäytettävyyden ja ylläpidettävyyden parantamiseksi. Lisäksi kehitin tässä tutkimuksessa tarkastusohjeen, joka sisältää keskeiset ominaisuudet dokumentaation sisällön arvioimiseksi uudelleenkäytön näkökulmasta. Tämä opinnäytetyö edistää osaltaan dokumentaation jäsentämis- ja refaktorointitarpeiden ymmärtämistä DITA XML:llä kirjoitettujen dokumenttien uudelleenkäytettävyyden parantamiseksi. Löydökset toimivat arvokkaana resurssina dokumentointitiimeille, jotka pyrkivät luomaan johdonmukaisempia ja uudelleenkäytettäviä dokumentteja.