Mitä on Docs as Code?

Dokumentaation tyypillinen ongelma on se, että se jää jälkeen tuoteversioista tai se ei vastaa modulaarisen tuotteen eri versioita. Modulaarisella lähestymistavalla voidaan kohdentaa dokumentaatio vastaamaan tuotekonfiguraatiota. Menetelmän tavoitteena on yhdistää tuotteen ja sen dokumentaation kehitys. Tämä saavutetaan soveltamalla dokumentointiin samoja hyväksi havittuja työkaluja ja menetelmiä kuin ohjelmistokehitykseen. Nämä työkalut ja menetelmät vaihtelevat organisaatioittain. Docs as Coden lähtökohdat ovat:

– Dokumentti on standarditekstiformaatissa, kuten DITA, HTML tai Markdown. Näitä voidaan muokata niille kehitetyillä tekstieditoreilla, esimerkiksi Oxygen XML Editor.

– Palvelunhallintajärjestelmä (esim. Jira) muutostenhallintaan, jota käytetään tyypillisesti myös ohjelmistokehityksessä. Tarkoituksena on varmistaa, että tuotteen muutokset näkyvät myös dokumentaatiossa.

– Versiohallinta (Git), Docs as Code -menetelmässä dokumentointi tyypillisesti seuraa dokumentoitavan tuotteen versioita. Vaihtoehtoisesti voidaan käyttää Indox CCMS -järjestelmää, jossa on tuki työnkuluille.

– Automaattinen dokumentaation koostaminen ja jakelu. Mikäli dokumentaatioon tulee muutoksia se laukaisee koostamisen, jonka myötä syntyy uudelle versiolle sopiva dokumentaatio. Tämä vastaa ohjelmistokehityksen CI/CD-ajattelua, eli jatkuvaa integraatiota ja jatkuvaa toimitusta. Dokumentaation modulaarisuuden ansiosta voidaan koostamisessa kohdentaa dokumentaatio vastaamaan asiakkaan tuotekonfiguraatiota.

– Dokumentaation testaus voidaan automatisoida esim. validoimalla DTD/skeemaa vastaan ja käyttämällä terminologian tarkastukseen automaatiota kuten Vale-sovellusta.

– Dokumentointi yhdistetään käytettävään kehitysmenetelmään. Esimerkiksi ohjelmistokehityksen Scrum, jolloin dokumentointi tehdään osana sprinttejä.

Docs as Code -menetelmä voidaan toteuttaa siten, että koko kehitystiimi on vastuussa dokumentaatiosta. Ohjelmistokehittäjät osallistuvat dokumentointiin osana kehitystyötä kirjoittamalla Markdownilla tai DITAlla. Tekniset kirjoittajat stilisoivat ja järjestelevät aineiston.

DITA sopii erinomaisesti Docs as Code -menetelmään

DITA on Oasis-standardin mukainen tekstipohjainen formaatti, joka on mahdollistaa aineiston siirron järjestelmästä toiseen tai työkalujen vaihtamisen vaivatta. DITAan voi yhdistää muitakin tekstipohjaisia formaatteja, kuten Markdown ja HTML (LWDITA). Tekstipohjaisuuden ansiosta voidaan käyttää versiointityökaluja ja vertailu on helppoa. DITAn modulaarisuus ja uudelleenkäytettävyys helpottavat erilaisten dokumenttikokonaisuuksien koostamista samasta lähdeaineistosta. DITA mahdollistaa useat erilaiset jakeluformaatit, kuten html (WebHelp) ja PDF. Julkaisu tehdään tyypillisesti käyttäen vapaanlähdekoodin DITA-OT-työkalua. DITAn semanttisuus mahdollistaa monimuotoisen testaamisen. Konteksti voidaan huomioida testaamisessa, esimerkiksi otsikot pitää olla tietyssä muodossa.

Johtopäätökset

DITA sopii hyvin Docs as Code -menetelmään. DITAlla voidaan tehdä monimutkaista dokumentaatiota, mutta helpompaan dokumentaatioon se voidaan pitää yksinkertaisena. DITA mahdollistaa dokumentaation hallitun kehittymisen tuotteen monimutkaistuessa vuosien aikana. Index IT auttaa organisaatiotasi siirtymään Docs as Code -menetelmään.

Lähteet:

https://istc.org.uk/wp-content/uploads/2021/11/George-Bina-%E2%80%93-Docs-as-Code-and-DITA.pdf