From Waste to an Asset: An Action Research Study to Improve Documentation Effort in a Scrum Team

Abstract

Documentation in continuous software development is a challenging task with many contradictions. As agile practitioners often perceive documentation as waste or a throwaway resource while developing a software increment, it is evident that there are many needs in a software organization that could benefit greatly from existing documentation.

This thesis reports on a canonical action research (CAR) project with Statistics Finland as the client. The Scrum team forming the action team in this research has been struggling with a lack of reliable information that can be easily discovered. As a result, the thesis will present ways to improve creation of purposeful documentation in agile workflow. Qualities of a purposeful documentation are discussed, along with ways to improve information discoverability among scattered documentation. The main findings of this thesis are that outdated documentation and absence of relevant documentation hinders development work. Another problematic theme is the question of how to efficiently discover needed information and how to keep scattered documentation up-to-date. The diagnosis findings suggest that scattered documentation increases the risk to have outdated documentation. The main reason for many documentation related problems is the lack of established documentation practices in continuous software development.

The result of the thesis suggests that if documentation is perceived as an agile artefact with value, it will result in purposeful documentation that is easier to keep updated. The approach to documentation in agile software development should be aligned with the software increments and normal agile artefacts such as readme-files and tests, and they should be used as a core of the documentation. Using proper tools can increase the efficiency of documentation and help to increase the discoverability of information. When the documentation practices are established to support the stakeholder’s needs, it is possible to automate recurring documentation tasks to align with core agile practices such as continuous integration and continuous delivery.

Dokumentaatio osana jatkuvaa kehitystä on haastava aihe, joka sisältää useita ristiriitoja. Ketterän kehityksen puolestapuhujat ajattelevat usein, että dokumentaatio on turhaa ja siihen käytetty aika on hukkaan heitettyä. On kuitenkin selvää, että ohjelDokumentaatio osana jatkuvaa kehitystä on haastava aihe, joka sisältää useita ristiriitoja. Ketterän kehityksen puolestapuhujat ajattelevat usein, että dokumentaatio on turhaa ja siihen käytetty aika on hukkaan heitettyä. On kuitenkin selvää, että ohjelmistotuotteita ja palveluita tarjoavat organisaatiot voisivat hyötyä dokumentaatiosta.

Tämä diplomityö esittelee kanonisella toimintatutkimusmenetelmällä toteutetun projektin, joka on tehty yhteistyössä Tilastokeskuksen kanssa. Scrum tiimi, joka osallistui tutkimukseen, on kärsinyt luotettavan tiedon puutteista sekä tiedon hankalasta löydettävyydestä. Lopputuloksena esitellään keinoja, joilla voidaan parantaa tarkoituksellisen dokumentaation tuottamista osana ketterää kehitystä. Lisäksi esitellään tarkoituksenmukaiselle dokumentaatiolle tyypillisiä ominaisuuksia sekä keinoja helpottaa tiedon löytämistä hajautetuista lähteistä.

Tärkeimmät löydökset osana diagnosointia voidaan jakaa tiedon löydettävyyden ja ylläpidon haasteisiin sekä niiden vaikutuksiin. Vanhentunut tai hankalasti löydettävä dokumentaatio vaikeuttaa kehitystyötä. Hajautettu dokumentaatio tekee tiedosta hankalasti löydettävää ja vaikeuttaa sen pitämistä ajan tasalla. Iso osa haasteista liittyy epäsuorasti jatkuvaan kehitykseen ja siihen, että dokumentaatio ei yleisesti ole kuvattu tärkeänä osana kyseistä ideologiaa.

Näihin haasteisiin voidaan vastata tunnustamalla dokumentaatio yhdeksi artefaktiksi tuotantokoodin ohella, joka tuottaa arvoa. Kun dokumentaation arvo ymmärretään, se motivoi tuottamaan parempilaatuista dokumentaatiota, jonka ylläpitämiseen sitoudutaan paremmin. Dokumentointi kannattaa ottaa osaksi käytettyä ketterää kehitysmallia, joka tuo dokumentoinnin osaksi toteutustyötä. Tästä syntyvät artefaktit testeistä readme-tiedostoihin muodostavat dokumentaation ytimen, jota voidaan linkittää sekä täydentää tarpeen mukaan. Oikein valituilla työkaluilla voidaan dokumentaatiokäytäntöjä suoraviivaistaa sekä parantaa tiedon löydettävyyttä. Dokumentaation automatisointi voidaan aloittaa, kun käytännöt ovat vakiintuneet. Automaatio on tärkeä aihe, kun halutaan tuoda dokumentaatio osaksi ketterän kehityksen käytäntöjä kuten jatkuvaa integraatiota ja jatkuvaa toimitusta. mistotuotteita ja palveluita tarjoavat organisaatiot voisivat hyötyä dokumentaatiosta.

Tämä diplomityö esittelee kanonisella toimintatutkimusmenetelmällä toteutetun projektin, joka on tehty yhteistyössä Tilastokeskuksen kanssa. Scrum tiimi, joka osallistui tutkimukseen, on kärsinyt luotettavan tiedon puutteista sekä tiedon hankalasta löydettävyydestä. Lopputuloksena esitellään keinoja, joilla voidaan parantaa tarkoituksellisen dokumentaation tuottamista osana ketterää kehitystä. Lisäksi esitellään tarkoituksenmukaiselle dokumentaatiolle tyypillisiä ominaisuuksia sekä keinoja helpottaa tiedon löytämistä hajautetuista lähteistä.

Tärkeimmät löydökset osana diagnosointia voidaan jakaa tiedon löydettävyyden ja ylläpidon haasteisiin sekä niiden vaikutuksiin. Vanhentunut tai hankalasti löydettävä dokumentaatio vaikeuttaa kehitystyötä. Hajautettu dokumentaatio tekee tiedosta hankalasti löydettävää ja vaikeuttaa sen pitämistä ajan tasalla. Iso osa haasteistaliittyy epäsuorasti jatkuvaan kehitykseen ja siihen, että dokumentaatio ei yleisesti ole kuvattu tärkeänä osana kyseistä ideologiaa.

Näihin haasteisiin voidaan vastata tunnustamalla dokumentaatio yhdeksi artefaktiksi tuotantokoodin ohella, joka tuottaa arvoa. Kun dokumentaation arvo ymmärretään, se motivoi tuottamaan parempilaatuista dokumentaatiota, jonka ylläpitämiseen sitoudutaan paremmin. Dokumentointi kannattaa ottaa osaksi käytettyä ketterää kehitysmallia, joka tuo dokumentoinnin osaksi toteutustyötä. Tästä syntyvät artefaktit testeistä readme-tiedostoihin muodostavat dokumentaation ytimen, jota voidaan linkittää sekä täydentää tarpeen mukaan. Oikein valituilla työkaluilla voidaan dokumentaatiokäytäntöjä suoraviivaistaa sekä parantaa tiedon löydettävyyttä. Dokumentaation automatisointi voidaan aloittaa, kun käytännöt ovat vakiintuneet. Automaatio on tärkeä aihe, kun halutaan tuoda dokumentaatio osaksi ketterän kehityksen käytäntöjä kuten jatkuvaa integraatiota ja jatkuvaa toimitusta.