Using and advancing DITA XML : A case study of evaluating DITA-authored customer documentation

Abstract

In today’s world, customer documentation for products must comply with the changing needs of the users, who want to access and consume information effortlessly as soon as they need it. Traditional documentation strategies such as desktop publishing and linear writing have been challenged by the emerging technologies in technical communication that emphasize modularity, flexibility and efficiency from both the users and the technical writers’ perspectives. The Darwin Information Typing Architecture (DITA) is one of the most interesting technologies within the technical communication field. The theoretical framework of this study is based on markup languages – especially DITA – and various perspectives of technical writing, such as topic-based writing, single-sourcing and minimalism. The features of DITA and the best practices of structured writing offer a lucrative starting point for addressing the highly practical research question of this study, namely how DITA XML has been used. This thesis is done in collaboration with a large company’s business unit that produces highly complex products and whose technical documentation strategy includes writing use case-based DITA topics. Now, the unit has initiated a transformation project whose goal is to evolve the customer documentation, and this thesis is a part of this project. The research problem of this thesis was approached by conducting a heuristic evaluation by using the DITA heuristics that were created as a part of this study, as such heuristics did not exist yet. The heuristics are based on both literature and practical experience on authoring technical documentation in DITA, as well as the business unit’s internal guidelines and discussions with a senior documentation specialist with extensive knowledge and competencies of the themes of this thesis. The DITA heuristics will later serve as a basis for a tool for the technical writers at the unit. The research data comprises 80 DITA XML modules, 40 of which contain descriptive, conceptual information (DITA concept topics) while the remaining 40 guide the users on carrying out procedures (DITA task topics). The sample data dates to 2021, and it was collected from the customer documentation of four different software components. The research shows that DITA can be used in various ways to author technical documentation, but some practices conform better to the principles of the DITA standard as well as the guidelines of structured, modular documentation. The most central issues include semantic markup, information typing and minimalism, especially task-orientation. Moreover, conducting a heuristic evaluation with a customized heuristics list proved to be an effective method for assessing the practices of authoring customer documentation in DITA. The results of this thesis provide valuable information for the business unit’s endeavors in terms of evolving their customer documentation content and presentation as well as supporting technical writers. The results of this thesis can be used internally in the business unit as a part of their transformation project regarding the usability and user-centeredness of their customer documentation. As a continuum to this study, technical writers who use DITA could be researched in terms of how they perceive DITA and structured authoring to increase the knowledge of how these themes are regarded among technical documentation experts today.

Asiakasdokumentaation käyttäjät sekä heidän tapansa ja tarpeensa ovat muuttuneet ajan saatossa, minkä seurauksena myös itse dokumentaatio on muuttunut. Teknisen viestinnän alalla on havaittu, että käyttäjät haluavat saada tarvitsemansa tiedon nopeasti juuri sillä hetkellä, kun he sitä tarvitsevat. Tästä syystä perinteinen lineaarinen dokumentaatio, jossa käyttöohjeet kirjoitetaan kokonaisuutena alusta loppuun sivu-sivulta-periaatteella on alkanut väistyä uusien metodien tieltä, jotka painottavat modulaarisuutta, joustavuutta ja tehokkuutta niin käyttäjien kuin informaatiota tuottavien teknisten kirjoittajienkin näkökulmasta. Yksi alan suosituimmista tähän tarkoitukseen sopivista metodeista on Darwin Information Typing Architecture eli DITA. Tämän pro gradu -tutkielman teoreettinen viitekehys rakentuu merkintäkielten (etenkin DITAn) ja teknisen viestinnän eri periaatteiden ja hyvien käytäntöjen ympärille, joihin sisältyvät modulaarisuus, yksilähteistäminen ja minimalismi. Tutkimuskysymys on hyvinkin käytännöllinen, nimittäin tässä tutkielmassa tarkastellaan DITA XML:llä tuotettua dokumentaatiota sen lähtöformaatissa. Tutkielma on tehty yhteistyössä erään suuren yrityksen kompleksisia tuotteita valmistavan liiketoimintayksikön kanssa, jossa olen ollut harjoittelussa teknisenä kirjoittajana. Yksikössä tuotetaan itse tuotteiden lisäksi myös niiden dokumentaatio, ja DITA on tämän dokumentointistrategian ytimessä. Yksikössä on käynnistetty transformaatioprojekti, jonka tarkoituksena on kehittää asiakasdokumentaatiota entisestään. Tämä tutkielma on osa tuota projektia. Tutkimuskysymystä lähestyttiin toteuttamalla heuristinen arviointi dokumentaatiolle. Tutkielmassa esitellyt ja käytetyt DITA-heuristiikat luotiin osana tutkimusta, sillä vastaavia heuristiikkoja ei ollut luotu aiemmin. Heuristiikat pohjautuvat teoreettiseen ja käytännön tuntemukseen dokumentoinnista DITAa käyttäen, minkä lisäksi niiden taustalla vaikuttavat yksikön sisäiset ohjeistukset ja käytänteet sekä keskustelut ja yhteistyö yksikön dokumentaatioasiantuntijan kanssa, jolla on kattava kokemus ja tietämys tutkielmaan liittyvistä aihepiireistä. Tutkimusaineisto kattaa 80 DITA-topiikkia eli yksittäistä moduulia neljästä eri ohjelmistotuotekomponentista. Topiikeista 40 käsittelee konseptuaalista informaatiota komponenteista, kun taas toiset 40 kuvailevat tehtäviä, joita komponenttien käyttäjät noudattavat. Aineisto on peräisin vuodelta 2021. Tutkimuksen tulokset osoittavat, että DITAa voidaan soveltaa monilla eri tavoilla dokumentaatiossa, mutta tietyt tavat toteuttavat DITAn arkkitehtuuria muita paremmin. Lisäksi tapojen välillä havaittiin olevan eroja sen suhteen, miten hyvin ne vastaavat rakenteisen ja modulaarisen tekstin kirjoittamisen konventioita. Olennaisimmat havainnot liittyvät semanttisen merkintäkielen käyttöön, minimalismiin ja informaatiotyypittelyyn sekä käyttäjän ydintehtävien korostamiseen tuoteominaisuuksiin keskittymisen sijaan. Tutkimuksen johtopäätökset tarjoavat käyttökelpoista tietoa yksikön transformaatioprojektin tarpeisiin, ja niitä tullaankin käyttämään osana asiakasdokumentaation kehittämistä. Tutkimuksen perusteella jatkotutkimuksen aiheena voisi olla esimerkiksi DITAa käyttävien teknisten kirjoittajien suhtautuminen tässä tutkielmassa käsiteltyihin rakenteellisen kirjoittamisen ja modulaarisuuden teemoihin. Näin olisi mahdollista saada ajankohtaista tietoa siitä, miten alan ammattilaiset näkevät DITAn ja sen käyttökelpoisuuden.