Software Knowledge: Robust Documentation Model in Quantified Informationspace

Abstract

The development of software is a complex process, and often a team effort. At its simplest, those who make the software and those use it comprise the entirety of its stakeholders, but the modern domain of commercial software features systems of such scale and scope, that stakeholders have to be considered in geographically. Traditional documentation practices and tools were not designed with such a broad audience in mind, and the author noted the challenge this poses for software development, which underscored the need for research. The research commenced with a literature review. The purpose of and definitions for the subject of Software Documentation were explored by evaluating related standards and studies, which were also reviewed for how they consider stakeholder diversity. The characteristics of the subject was also discussed, which was followed by a review of current technologies and tools of relevance. The research concluded with a Future Workshop that brought together a diverse array of stakeholders, where the participants were asked to critique the present state of documentation, and envision more desirable futures for it.

The results comprise of 35 critique points in 8 categories, and three implementation plans for reaching the ideal futures, as imagined by the participants. These were integrated into the Robust Documentation Model, which is proposed as a new approach for comprehending Software Documentation. An example implementation demonstrates its feasibility.

Every implementation plan incorporated significant use of AI, which is expected to have a profound impact in the future. However, the key finding of the research was that no single system or solution alone can fully address all the challenges in Software Documentation, unless software development is treated as a collaborative endeavour involving diverse set of stakeholders, each with unique documentation needs.

Yksinkertaisimmillaan ohjelmiston sidosryhmät koostuvat sen kehittäjistä sekä sen käyttäjis- tä. Modernilta kaupallisen sovelluskehityksen kentältä löytyy kuitenkin maailmanlaajuisia verkkopalveluja, joissa sidosryhmiä joudutaan käsittelemään jopa maantieteellisesti. Perintei- siä ohjelmistokehityksen dokumentaation menetelmiä ja työkaluja ei alunperin suunniteltu näin laajoille sidosryhmille, jonka opinnäytetyön kirjoittaja näki haasteena ohjelmistokehityk- selle, sekä osoituksena uuden tutkimuksen tarpeellisuudesta.

Tutkimus käynnistyi kirjallisuuskatsauksella, jossa ohjelmistokehityksen dokumentaation määritelmiä lähestyttiin tarkoitushakuisesti analysoimalla aiheseen liittyviä standardeja ja tukimuksia. Lisäksi tutkittiin sitä, miten sidosryhmien diversiteetti oli näissä huomioitu. Myös asiaankuuluvaan teknologiaan perehdyttiin. Tutkimus kulminoitui tulevaisuuspajaan, jossa eri sidosryhmistä koostuvat osanottajat tunnistivat nykytilaa vaivaavia ongelmia kritiikin kautta. Tämän jälkeen visioitiin millainen olisi ihanteellinen tulevaisuus, ja lopulta askeleet tuon tulevaisuuden saavuttamiseksi dokumentoitiin kolmeen toteutussuunitelmaan. Näiden lisäksi tutkimuksen tuloksiin kuuluu 35 tunnistettua kritiikin kohdetta sekä niiden 8 kategori- aa. Tuloksia hyödynnettiin uuden dokumentaatiomallin kehittämisessä, jonka kelpoisuutta ohjelmistokehitykseen esiteltiin esimerkkitoteutuksella.

Generatiivinen tekoälyteknologia oli kaikkien toteutussuunnitelmien keskiössä, ennustaen merkittävää vaikutusta dokumentaation tulevaisuudelle. Tutkimuksen tärkein huomio oli kui- tenkin se, että kaikkien ohjelmistokehityksen dokumentaatioon liittyvien ongelmien ratkaise- minen on mahdollista vain jos ohjelmistokehitys nähdään eri sidosryhmien yhteistyöhön perustuvana hankkeena, jossa näiden tarpeet ohjelmiston ymmärtämiseksi vaihtelevat.