Dokumentti on kirjallinen kuvaus järjestelmästä [2], jonka tarkoituksena on sisältää hyödyllistä tietoa suunnitellulle kohdeyleisölle [4]. Ohjelmiston dokumentaatiolle on useita erilaisia käyttäjiä, jotka ovat eritasoisia ammattitaidoltaan ja omaavat toisistaan poikkeavia tiedontarpeita. Tämän vuoksi dokumentaatio on hyvä jakaa useisiin dokumentteihin, jotka vastaavat jokainen johonkin tiettyyn ongelmaan, sen sijaan, että kaikki informaatio esitettäisiin yhdessä isossa dokumentissa. Kohdeyleisön lisäksi dokumenttien sisältöön ja formaattiin vaikuttaa myös dokumenttien laatijoiden ammattitaito ja saatavilla oleva informaatio.[1,2]
Sommerville kategorisoi erityyppiset ohjelmistotuotteen dokumentit jakamalla ne kahteen pääluokkaan, jotka ovat järjestelmän dokumentit ja käyttäjän dokumentaatio. Nämä voidaan taas jakaa yhä tarkempiin kokonaisuuksiin ja näin saadaan suhteellisen kompakteja dokumentteja, jotka vastaavat kohdeyleisön tiedontarpeisiin. Esimerkiksi käyttäjän dokumentit voidaan jakaa loppukäyttäjille tai järjestelmänvalvojille suunnattuihin dokumentteihin. Loppukäyttäjien dokumenteissa kuvaillaan miten ohjelman eri ominaisuuksia käytetään keskittymättä ohjelmiston sisäiseen toimintaan.
Järjestelmänvalvojan dokumenteissa voidaan taas kuvailla esimerkiksi joitakin järjestelmän ylläpitoon liittyviä tehtäviä tai sitä miten ohjelmisto asennetaan johonkin tiettyyn ympäristöön. Toinen pääluokka, eli järjestelmän dokumentit käsittelee enemmän ohjelmiston sisäistä toteutusta ja näiden dokumenttien kohdeyleisönä on pääosin ohjelmistokehittäjät. [1]
6 2.2 Dokumentoinnin hyödyt
Useat alan harjoittajat pitävät lähdekoodia riittävänä informaation lähteenä, mutta käytännössä suurin osa ohjelmista on kuitenkin niin monimutkaisia, että niiden toiminnan ymmärtämiseen tarvitaan erillisiä dokumentteja. Tiedon etsiminen suoraan lähdekoodista voi olla todella haastavaa, sillä lähdekoodi sisältää valtavan määrän informaatiota, josta suurin osa ei ole toiminnan ymmärtämisen kannalta oleellista. Tämän vuoksi tehdään dokumentteja, joissa on lähdekoodista tiivistettyä informaatiota selkeässä muodossa esitettynä. [2] Shmerlinin et al. tutkimuksessa haastateltiin eri yrityksissä työskenteleviä ohjelmistokehittäjiä, jotka totesivat, että dokumentaatio auttaa heitä ymmärtämään lähdekoodin eri osia. Haastateltavien mukaan myös oman koodin ymmärtämiseen on hyvä olla saatavilla erillisiä dokumentteja. [5]
Hyvällä dokumentaatiolla voidaan säästää paljon aikaa ohjelmistoprojektin eri vaiheissa ja vaiheiden aikana ilmenevissä eri tilanteissa. Esimerkiksi tilanne, jossa uusia työntekijöitä tuodaan mukaan keskeneräiseen ohjelmistoprojektiin, voi pitkittää prosessia. Ollakseen hyödyllisiä projektin etenemisen kannalta, uudet tulokkaat tarvitsevat informaatiota järjestelmän toiminnasta. Dokumentaatio voi toimia apuna tässä, sillä mitä nopeammin tulokkaat ymmärtävät ohjelmiston toiminnan, sitä vähemmän resursseja tähän opiskeluvaiheeseen joudutaan käyttämään. Dokumentaation puute aiheuttaa myös sen, että uusien työntekijöiden lisäksi myös vanhojen työntekijöiden tehokkuus kärsii, sillä ilman dokumentaatiota he joutuvat auttamaan tulokkaita projektin tarvittavien tietojen selvittämisessä. [2]
Dokumentaation merkitys korostuu erityisesti ohjelmistoprojektin ylläpitovaiheessa, sillä tässä vaiheessa ohjelmistokehittäjät käyttävät usein enemmän kuin puolet ajastaan koodin toiminnan ymmärtämiseen. Ylläpitovaiheessa usein muokataan joitakin ohjelmiston ominaisuuksia tai korjataan ilmenneitä virheitä. Näihin työtehtäviin käytettävää aikaa voidaan pienentää hyvällä dokumentaatiolla. [2] Vuonna 1995 Yipin tutkimuksessa huomattiin, että Hong Kongissa tehtyjen ohjelmistoprojektien kustannuksista noin 66%
kului ylläpitovaiheessa. Tutkimuksen mukaan huono dokumentaatio oli yksi suurimmista ongelmien aiheuttajista ohjelmiston ylläpitovaiheessa. [6] Tryggesethin suorittamassa kokeessa tutkittiin, miten saman taitotason omaavat koehenkilöt suoriuituivat samasta
7
ylläpitotehtävästä, jossa ohjelmistoon tuli tehdä parannuksia sekä ohjelmiston toiminnallisuuksia tuli muuttaa. Koehenkilöt jaettiin kahteen ryhmään, joista vain toisella oli käytössä dokumentit ohjelman vaatimusmäärittelystä, suunnitelusta, testiraporteista ja käyttöohjeista. Molemmat ryhmät käyttivät eniten aikaa järjestelmän toiminnan ymmärtämiseen, mutta ryhmä jolla ei ollut käytössä mainittuja dokumentteja käytti tähän 21,5% enemmän aikaa kuin ryhmä, jolla oli dokumentit käytössä. [7]
Tryggesethin tutkimuksessa ryhmä, jolla oli dokumentit, teki yksityiskohtaisempaa ja laadukkaampaa jälkeä kuin toinen ryhmä, sillä heillä oli parempi ymmärrys ylläpitotehtävistä sekä enemmän aikaa tehtävien suorittamiseen [7]. Myös Shmerlinin et al.
tutkimuksen haastateltavien mukaan dokumentaation avulla koodista voi tulla järjestelmällisempää ja laadukkampaa [5]. Lisäksi, jos ohjelmistoon halutaan tehdä muutoksia turvallisesti, tarvitaan hyvä ymmärrys koodin toiminnasta ja siitä mitkä eri osat vaikuttavat toisiinsa. Dokumentaatio auttaa tässä kokonaisuuden hahmottamisessa ja näin helpottaa muutosten tekoa aiheuttamatta ohjelmointivirheitä. [2]
Hyvä dokumentaatio on välttämätöntä lähes jokaisessa avoimen lähdekoodin projektissa.
Geiger et al. tutkivat avoimen lähdekoodin ohjelmistojen dokumentaation vaikutuksia haastattelemalla data-analytiikkaan liittyviin projekteihin osallistujia. Vaikka tutkimus suoritettiin juuri data-analytiikkaan liittyen, sen ajateltiin pätevän myös laajempaan kategoriaan avoimen lähdekoodin projekteja. Haastateltavat tunnistivat monia eri hyötyjä liittyen dokumentointiin. Useiden haastateltavien mukaan tärkein dokumentaation käyttötarkoitus on palauttaa mieleen ohjelmiston toiminta. Myös omien tuotoksiensa dokumentointi on osoittanut tärkeäksi, sillä vuosia sitten tehtyjen ohjelmistojen tai moduulien toiminta unohtuu helposti. Eniten mainittu hyöty oli kuitenkin dokumentaation suuri rooli opetusmateriaalina. Haastateltavat tunnistivat erilaisia oppijoita ja eri vaiheita oppimisprosessissa. Esimerkiksi jo ohjelmiston kanssa entuudestaan tutut käyttäjät saattavat katsoa dokumenteista tarkkoja yksityiskohtia funktioiden toiminnasta, kun taas aloittelija saattaa katsoa onko hänen tarpeisiinsa saatavilla jotakin funktiota. Esimerkit ohjelmiston käyttötapauksista ovat tärkeitä erityisesti aloittelijoita varten. Haastateltavien mukaan jos aloittelijat eivät onnistu ongelmien ratkaisussa ohjelmiston avulla eikä saatavilla ole dokumentaatiota miten kyseinen asia ratkaistaan, he lopettavat ohjelman käytön. Monet mainitsivat myös miten dokumentaatio auttaa ohjelmistokehittäjiä yhteistyössä. Kun
8
esimerkiksi Application Programming Interface -dokumentaatio (API) sisältää keskeiset asiat jonkin moduulin toteutuksesta, on siihen helppo viitata kuvailtaessa kohtaa johon muutokset tulee tehdä. Haasteltavat mainitsivat myös, että dokumentaatio voi toimia mainoksena ohjelmistolle. Koska useille ongelmille on yleensä saatavilla monia eri avoimen lähdekoodin ohjelmistoja, käyttäjät joutuvat valitsemaan kilpailevien ohjelmistojen väliltä minkä ohjelman he haluavat omiin tarpeisiinsa käytettäväksi. Jotkut haastateltavat pitivätkin dokumentaatiota ratkaisevana tekijänä tässä valinnassa. Esimerkiksi eräs haasteltava toi esille tilanteen, jossa hän ei ottanut käyttöön uutta ohjelmistoa, sillä siitä ei ollut saatavilla esimerkkitapauksia juuri sitä ongelmaa varten mitä hän oli ratkaisemassa. [8]
2.3 Dokumentointiin liittyvät ongelmat ja seuraukset
2.3.1 Dokumentointiprosessin ongelmat
Dokumentaatio ja luotujen dokumenttien ylläpito aiheuttavat merkittävän määrän ohjelmistoprojektin kustannuksista, mistä johtuen alan tutkijoiden ja harjoittajien tulee arvioida dokumentaation hyödyn ja siihen tarvittavien resurssien välistä suhdetta. Zhin et al.
suorittaman järjestelmällisen kirjallisuuskatsauksen mukaan dokumentaation kustannuksien tutkimus on kuitenkin jäänyt vähälle verrattuna alan muuhun tutkimukseen. [3] Eräässä Nasan organisaatiossa tunnistettiin dataa analysoimalla, että heidän ohjelmistoprojekteissaan kului tyypillisesti 11 % resursseista dokumentointiin. [9]
Organisaation on helppo tunnistaa, miten paljon resursseja dokumentoinnin toteuttamiseen on kulunut. Dokumentaation laiminlyönnistä aiheutuvia kuluja, on taas paljon hankalampi arvioida. Jos dokumentaatiota ei toteuteta, sillä voi olla vaikutuksia moniin eri ohjelmistoprojektin tehtäviin. Esimerkiksi ohjelmistovirheiden, tietoturva-aukkojen tai muiden ohjelmiston ominaisuuksien korjaamiseen tai muokkaamiseen käytetty aika voi lisääntyä puuttellisen dokumentaation vuoksi, mikä voi johtaa projektin kustannusten kasvuun. [1]
Geigerin et al. tutkimuksessa selvisi, että motivaation puute on yksi suurimmista ongelmista avoimen lähdekoodin ohjelmistojen dokumentaatioon osallistumisessa. Haastateltavat kokivat ettei dokumentaatiotyöstä saa samanlaista arvostusta yhteisöltä kuin ohjelmiston vikojen korjaamisesta ja ominaisuuksien kehittämisestä. Motivaation puute johtuu arvostuksen lisäksi myös yksinkertaisesti siitä, ettei dokumentointiprosessia pidetä yhtä
9
miellyttävänä kuin edellä mainittuja. Toisena suurena haastateltavien ongelmana olivat puutteliset taidot, joita dokumentointiin vaaditaan. Useissa projekteissa esimerkiksi API-dokumentaatio generoidaan lähdekoodiin kirjoitettujen kommenttien avulla. Erityisesti tämänkaltaisissa projekteissa dokumentointiin osallistuminen vaatii tiettyjä teknisiä taitoja, kuten projektissa käytettyjen teknologioiden tuntemus ja versionhallinnan käyttö. Teknisten taitojen lisäksi vaaditaan taitoja kommunikoinnissa, luovassa kirjoittamisessa, englannin kielessä ja empatiassa. Empatialla tarkoitetaan tässä asiayhteydessä kykyä asettua kokeneempana ohjelmistokehittäjänä aloittelijan asemaan tunnistaakseen minkälaista informaatiota kokeneemmatomampi voisi tarvita. [8] Shmerlinin et al. tutkimuksen haastateltavien mukaan dokumentointi oli epämiellyttävää myös yrityksissä työskentelevien ohjelmistokehittäjien mielestä. Jotkut mainitsivat dokumentoinnin tuntuvan turhalta, sillä metodien toiminta on itsestäänselvyys niiden kehittäjille. Tutkimuksesta selvisi myös, ettei dokumentointiin riitä yleensä aikaa ja jos projektilla on aikaraja, niin dokumentointi jää tekemättä. [5]
Vuonna 2019 tehdyssä empiirisessä tutkimuksessa Aghajani et al. tarkastelivat ohjelmistokehittäjien kohtaamia ongelmia dokumentaatioon liittyen keräämällä dataa monipuolisista lähteistä. Dataa kerättiin dokumentaatioon liittyvillä hakusanoilla Stack Overflow -viestiketjuista, Apache Software Foundationin sähköpostiarkistoista sekä GitHub projektien ongelmien seurannasta ja vetopyynnöistä (engl. pull request). Myös tämän tutkimuksen mukaan dokumentointiin osallistuminen aiheutti ongelmia, jotka johtuivat puutteellisista ohjeista tai taidoista. Jotkut eivät tienneet esimerkiksi, mihin kohtaan tarkalleen ottaen uusi informaatio tulisi lisätä dokumentissa, mitä osia dokumentista tarvitsisi parannella, miten dokumentointiin voi osallistua ulkopuolisena tai mihin dokumentaatio tulisi sijoittaa. Dokumentointiin käytettävät työkalut aiheuttivat myös ongelmia. Esimerkiksi ohjelmointivirheitä ilmeni, mikä on normaalia kaikenlaisille ohjelmistoille. Muita ongelmia aiheutui esimerkiksi, kun työkalut eivät pystyneet vastaamaan käyttäjän tarpeisiin puutteellisten ominaisuuksien vuoksi. Paljon keskustelua aiheutui myös, kun käyttäjät eivät olleet ymmärtäneet jonkin työkalun toimintoja. [4] Yksi tunnistettu puuttellinen ominaisuus työkaluille kuten, Javadoc, Doxygen tai Doc++, on se, että niillä voi tuottaa vain yhteen asiayhteyteen tarkoitettuja dokumentteja. Ohjelmistojen kehittäjillä ja käyttäjillä on kuitenkin erilaisia informaation tarpeita, joten olisi hyvä pystyä generoimaan useita eri dokumenttityyppejä lähdekoodista. [10]
10
2.3.2 Dokumentin informaatiosisältöön liittyvät ongelmat
Valmius (engl. completeness) kuvaa sitä, miten hyvin sisältö vastaa dokumentin käyttäjän tarpeisiin. Dokumentin katsotaan olevan vaillinainen, jos se ei sisällä käyttäjän tehtävien suorittamiseen vaadittavaa informaatiota [3]. Vuonna 2017 GitHub suoritti kyselyn kerätäkseen informaatiota avoimen lähdekoodin yhteisöjen toiminnasta, mietteistä ja projektien kehityskäytännöistä. Kyselystä saatiin selville, että 93 % vastaajista on kohdannut ongelmia vaillinaisista tai vanhentuneista dokumenteista johtuen. [11] Aghajanin et al.
tutkimuksessa vaillinaisuus käsitti 55 % dokumentin informaatiosisältöön liittyvistä ongelmista. [4] Myös Zhi et al. ajattelevat vaillinaisuuden olevan yksi suurimmista informaatiosisällön ongelmista, sillä suoritetun kirjallisuuskatsauksen mukaan se oli eniten käsitelty laadun ominaisuus [3]. Valmiuteen liittyviä ongelmia ovat esimerkiksi epäselvät termit, eli tapaukset, joissa käyttäjät eivät ymmärrä, mitä jollakin dokumentin osalla tarkoitetaan, koska käytetyt termit eivät ole tarkkoja ja yksiselitteisiä. Muita ongelmia ovat esimerkiksi puuttuvat kuvaukset ohjelmiston moduuleista, rajapinnoista tai yhteensopivuustiedoista. [4]
Oikeellisuudella (engl. correctness) kuvataan, perustuuko dokumentti tosiasioihin [3].
Virheellinen informaatio aiheuttaa turhia esteitä, vie aikaa ohjelmistokehittäjien tehtävien suorituksesta tai aiheuttaa muita seuraamuksia. Aghajanin et al. tutkimuksen yhdessä tapauksessa virheellisen dokumentin sokea noudattaminen johtaisi pysyvään tietojen menetykseen. Tutkimuksen artefaktien oikeellisuuteen liittyvät ongelmat kattoivat 15 % informaatiosisällön ongelmista ja johtuivat enimmäkseen virheellisistä koodiesimerkeistä.
Muita vähemmän esiintyviä ongelmia olivat virheelliset asennusohjeet ja lähdekoodin kommentit. Eräässä tapauksessa ongelmia aiheutui, kun dokumentissa viitattiin objekteihin, joita ei oltu edes vielä toteutettu ohjelmistossa. [4]
Ajantasaisuus (engl. up-to-dateness) kuvaa, miten dokumentti on pidetty ajantasalla verrattuna ohjelmistoon [3]. Tämä laadun mittari eroaa oikeellisuudesta ja valmiudesta siten, että dokumentti oli kunnossa ennen kuin ohjelmiston tehtiin jokin muutos. Aghajanin et al.
tutkimuksessa dokumentin ajantasaisuus käsitti toiseksi suurimman määrän informaatiosisällön ongelmista eli 39 %. Suurin ongelma liittyen ajantasaisuuteen oli ristiriitaisuudet dokumentin ja koodin välillä. Muita ongelmia olivat toimimattomat linkit,
11
linkit vanhentuneisiin dokumentin versioihin ja puuttuva dokumentti ohjelmiston uuteen versioon. [4] Ristiriitaisuus dokumentin ja ohjelmiston välillä voi aiheutua, kun ohjelmistoprojektissa esiintyy toistuvaa informaatiota eri formaateissa, kuten esimerkiksi lähdekoodissa, testitapauksissa ja dokumentaatiossa. Tässä tapauksessa jos jonkin metodin toimintaa muutetaan, dokumentista tulee ristiriitainen verrattuna ohjelmistoon. [12]
2.3.3 Dokumentin informaation esitystapaan liittyvät ongelmat
Aghajani et al. tutkimuksen mukaan eri alustoilla on käyty itse sisällön lisäksi myös paljon keskustelua siitä miten sisältö on esitetty. Eniten ongelmia dokumentin esitystapaan liittyen aiheutti dokumentin käytettävyys, eli se miten tehokkaasti käyttäjät saavuttavat tavoitteensa dokumentin avulla. Suurin syy joka alensi käytettävyyttä oli informaation löytämisen vaikeus. Näissä tapauksissa informaatio oli saatavilla, mutta käyttäjien mielestä se oli liian vaikea löytää. Muita ongelmia liittyen käytettävyyteen aiheutti sisällön huono formatointi ja informaation sijoittaminen paikkoihin, jossa niiden ei yleisesti oleteta olevan [4].
Dokumentin luettavuus (engl. readability) on subjektiivinen käsite, joka kuvaa miten selkeästi informaatio on esitetty dokumentissa [3]. Luettavuus oli Aghajani et al.
tutkimuksen toiseksi suurin tunnistettu ongelma liittyen informaation esitystapaan.
Käyttäjien mielestä jotkin dokumentit olivat liian sekavia, abstrakteja, teknisiä tai jaarittelevia. Myös yksinkertaisia kirjoitusvirheitä käsiteltiin joissakin artefakteissa. Muita ongelmia esitystapaan liittyen oli dokumentin ylläpidettävyys, joka kuvaa miten helppoa dokumenttiin on tehdä muutoksia ja oikaisuja. Ylläpidettävyys ongelmia muodostui esimerkiksi kun sama informaatio esitettiin useammassa kohdassa dokumentaatiota. [4]
2.4 Ongelmiin ehdoitettuja ratkaisuja
Zhin et al. kirjallisuuskatsauksen suurimmassa osassa tutkimuspapereista esiteltiin jotakin uutta tekniikkaa dokumentointiin tai parannusta vanhoihin tekniikoihin [3]. Esimerkiksi Nassif ja Robillard ehdottavat dokumentoinnin integroimista testitapausten kirjoittamiseen ratkaisuna toistuvasta informaatiosta aiheutuvaan ylimääräiseen työpanokseen ja ristiriitaisuuteen dokumentin sekä ohjelmiston välillä. Tässä lähestymistavassa ohjelman
12
yksikkötestit kirjoitettaisiin käyttäen sovittua rakennetta, mikä mahdollistaa dokumentin generoimisen. Menetelmän avulla dokumenttiin ei tarvitsisi kirjoittaa erikseen informaatiota, joka löytyy jo yksikkötesteistä. [12] Palmer ja McAddis taas esittävät dokumentin generointiin tarkoittettujen työkalujen puuttellisuuteen tuottaa dokumentteja useisiin eri asiayhteyksiin rakaisuna kehittämäänsä työkalua, jonka avulla pystytään tuottamaan eri asiayhteyksiin erilissiä dokumentteja lähdekoodiin kirjoitetuilla kommenteilla [10].
Myös Aghajani et al. esittivät joitakin mahdollisia ratkaisuja ongelmiin. He huomasivat, että oikeellisuuteen liittyvät ongelmat aiheutuivat enimmäkseen virheellisistä koodiesimerkeistä, sillä ohjelmointivirheet voivat vaikuttaa samalla tavalla myös dokumentin sisältämiin koodiesimerkkeihin kuin itse lähdekoodiinkin. Olisi siis suositeltavaa testata myös näitä koodiesimerkkejä samalla tyylillä kuin lähdekoodia, jotta varmistuttaisiin niiden oikeellisuudesta. Käytännössä tämä ei ole aina mahdollista sillä esimerkkikoodit ovat usein pieniä pätkiä lähdekoodista, joita ei voi kääntää tai ajaa sellaisenaan. Tässä on siis taas yksi ongelma, jota suositellaan tutkittavaksi tarkemmin. Aghajanin et al. mukaan joitakin käytännön asioita, joita voitaisiin toteuttaa parantaakseen dokumentaation laatua ovat esimerkiksi dokumentin käyttäjien mukaan ottaminen dokumentin tarkastamiseen sekä hakukoneiden, sisällysluettelon ja dokumentin sisäisten linkkien käyttäminen. Käyttäjien mukaan ottaminen tarkasteluun voi parantaa sisällön valmiutta, sillä jotkin käyttäjille epäselvät asiat saattavat vaikuttaa selkeiltä ohjelmistokehittäjien mielestä. [4]
13
3 DOKUMENTIN TOTEUTTAMINEN
Ohjelmiston dokumentaation voi toteuttaa useilla eri menetelmillä ja työkaluilla. Tietyssä projektissa käytettävien työkalujen valintaan voi vaikuttaa esimerkiksi dokumenttien tekijöiden taidot sekä menetelmät, joilla dokumentaatio toteutetaan. Esimerkiksi joissakin projekteissa dokumentaation voi toteuttaa tekniset kirjoittajat, jotka eivät osallistu itse ohjelmiston koodaamisen. Ohjelmistokehittäjillä on kuitenkin parempi tieto ohjelman toiminnasta kuin välikäsillä, joten heidän olisi suotavaa osallistua dokumentaation kirjoittamiseen.
Jos dokumentaation toteuttaa ohjelmistokehittäjät, jotka koodavat itse ohjelmistoa, voidaan käyttää esimerkiksi niin kutsuttua ”docs-as-code”-menetelmää. Menetelmä tarkoittaa sitä, että dokumentointi toteutetaan käyttäen samoja tekniikoita ja työkaluja kuin itse ohjelmiston koodaaminenkin. Näin dokumentoinnista tulee kehittäjäkeskeistä ja dokumentointiin osallistuminen helpottuu, sillä dokumentit voivat olla samassa tietovarastossa kuin lähdekoodi sekä dokumentteja voi muokata samassa ympäristössä ja samoilla työkaluilla kuin lähdekoodiakin. Esimerkiksi seuraavat työkalut ja tavat voivat olla käytössä ”docs-as-code”-menetelmässä:
• Dokumentit kirjoitetaan tekstitiedostoihin samaan tapaan kuin lähdekoodikin.
Käytetään jotakin merkintäkieltä, kuten esimerkiksi Markdown tai reStructuredText.
Merkintäkielellä kirjoitettua dokumentaatiota voidaan sisällyttää myös lähdekoodin kommentteihin.
• Dokumentit kootaan teksitiedostoista haluttuun muotoon jollakin ohjelmalla.
Käytetään esimerkiksi staatisten sivujen generointiin tarkoitettuja työkaluja (engl.
static site generator). Prosessoimattomat merkintäkielellä tehdyt dokumentit voidaan muuttaa haluttuun muotoon millä tahansa ohjelmalla, joka siihen soveltuu.
• Dokumentit kirjoitetaan tyypillisesti samalla tekstieditorilla kuin lähdekoodikin, mikä helpottaa ohjelmistokehittäjiä dokumentoimaan samalla kun he koodaavat.
• Versionhallinan käyttö. Auttaa yhteistyössä muiden dokumentin muokkaajien kanssa.
• Dokumenttien jatkuva julkaisu (engl. continuous delivery). Nopeuttaa muokattujen dokumenttien julkaisuprosessia.
14
Näiden tapojen lisäksi dokumenteille voidaan tehdä myös muita tyypillisiä ohjelmointiin liittyviä asioita, kuten testaaminen sekä sen automatisointi. Dokumenteista voidaan testata esimerkiksi formatointivirheet, kirjoitusvirheet, toimimattomat linkit tai mitä tahansa projektista riippuen täytyy testata. Nämä testit voidaan manuaalisen tarkistuksen sijaan tehdä automaattisesti esimerkiksi aina ennen dokumentin julkaisua.
Seuraavissa luvuissa esitellään joitakin yleisesti ohjelmistojen dokumentaatioon käytettäviä teknologioita ja niiden ominaisia piirteitä. Työkalujen esittelyn jälkeen esitetään yleisiä ohjeita tekniseen kirjoittamiseen.
3.1 Merkintäkielet
Tyypillisesti dokumentit koostuvat useista semanttisista elementeistä, eli erilaista informaatiota sisältävistä osista, joilla on jokin tietty tarkoitus ja esitystapa. Eri semanttisia elementtejä ovat esimerkiksi kappaleet, otsikot, leipäteksti, listat, lihavoinnit ja monet muut.
Kun dokumentteja tuotetaan merkintäkielien avulla, dokumentin informaatiosisältö ja informaation esitystavan määrittely erotellaan toisistaan. Merkintäkielten avulla siis esitetään vain informaatiosisältö sekä dokumentin semanttinen rakenne, käyttäen jokaiselle kielelle ominaisia tunnisteita, ottamatta kantaa siihen miten sisältö tullaan lopulta esittämään. [13] Moderneilla tekstinkäsittelyohjelmilla, kuten Microsoft Word, dokumentin informaatiosisältö ja sen esitystavan valinta ovat taas samassa paketissa. Näitä työkaluja käytettäessä käyttäjä näkee siis lopputuloksen jo dokumenttia muokatessaan. Työkalut, jotka mahdollistavat lopputuloksen reaaliaikaisen tarkastelun dokumenttia muokatessa, kutsutaan WYSIWYG-editoreiksi (engl. What You See Is What You Get). [1] Merkintäkielet siis keskittyvät tekstin asiasisältöön sekä semanttisten rakenteiden määrittelyyn, jättäen dokumentin esitystavan määrittelyn tehtäväksi vasta jälkeenpäin.
Kuva 1. havainnollistaa miten tekstinkäsittelyohjelmalla saadaan suoraan valmis dokumentti, kun taas merkintäkieliä käytettäessä joudutaan käyttämään jotakin ohjelmaa, jolla dokumentti formatoidaan haluttuun muotoon. Merkintäkieliä käytetään erityisesti docs-as-code menetelmässä. Koska merkintäkielillä tehdyt dokumentit ovat vain tekstitiedostoja, niitä voidaan prosessoida halutulla tavalla ennen kuin ne kootaan haluttuun lopulliseen muotoon.
15
Kuva 1. Dokumentaatio tekstinkäsittelyohjelmalla ja dokumentaatio merkintäkielillä.[1]
3.1.1 Markdown
Yksi tunnetuimmista merkintäkielistä on Markdown, jota käytetään laajasti useilla eri työkaluilla ja alustoilla. Esimerkiksi GitHub käyttää tyypillisesti Markdownia kaiken tekstin muotoiluun alustallaan, kuten esimerkiksi readme-tiedostoissa sekä vetopyyntö-keskusteluissa. Muita alustoja, jotka käyttävät Markdownia ovat esimerkiksi reddit, Stack Overflow ja useat eri blogisivustot. Erityisesti markdownia käytetään ohjelmistojen dokumentaatiossa, sekä muun staattisen sisällön tuottamisessa.
Markdownin kehittäjän John Gruberin mukaan kielen tärkein suunniteluperiaate oli kielen helppolukuisuus, ilman että tunnisteet ja muut formatointiohjeet häiritsisivät luettavuutta.
Kielen syntaksi on suuniteltu niin, että käytettävät tunnisteet näyttävät siltä mitä niillä tarkoitetaan, eli esimerkiksi semanttisten elementtien kuten listojen tunnisteet näyttävät samalta kuin lopullisen dokumentin listat. [14]
16
Markdownin syntaksi ei kuitenkaan ole täysin yksiselitteistä, minkä vuoksi samat dokumentit voivat näyttää erilaiselta eri alustoilla. Syntaksissa ei esimerkiksi ole määritelty yksiselitteisesti minkälaista sisennystä alaluetteloiden merkitsemiseen tulisi käyttää, pitääkö ennen otsikoita lisätä tyhjä rivi, voiko listoissa olla tyhjiä kohtia tai voidaanko listaan sisällyttää otsikoita. Markdownin epäjohdonmukaisuuksien ja kaksiselitteisyyden vuoksi kehiteltiin CommonMark kieli, jossa syntaksi on määritelty tarkasti. [15]
Tämän lisäksi Markdownista on kehitelty useita eri versioita, joissa on lisättyjä ominaisuuksia ja hieman erilaiset syntaksit. Esimerkiksi reddit-alustalla käytetään sille erityistä Markdowniin pohjautuvaa merkintäkieltä ja GitHubissa käytetään GitHub Flavored Markdown -kieltä (GFM). GFM joitakin laajennuksia Markdowniin, kuten esimerkiksi koodilohkojen osien korostukset, sekä joitakin syntaksin muutoksia.
3.1.2 reStructuredText
Toinen suosittu ja monien työkalujen käyttämä merkintäkieli on reStructuredText (RST, ReST tai reST). Jotkin työkalut käyttävät oletusarvoisesti ReST:iä merkintäkielenään, mutta myös työkalut ja alustat, kuten GitHub, joissa oletusarvoisesti käytetään Markdownia, tukevat usein myös ReST:in käyttöä. ReST pyrkii markdownin tapaan olemaan mahdollisimman yksinkertainen ja helposti luettava. Verrattuna Markdowniin, ReST on standardisoidumpi ja sen syntaksi noudattaa pääosin tiettyjä tarkkaan määriteltyjä sääntöjä.
ReST sisältää myös enemmän sisäänrakennettuja ominaisuuksia, kuten esimerkiksi sisällysluetteloiden luominen tai sitaatioiden esittäminen. Toki nämä ominaisuudet voidaan toteuttaa myös Markdownilla, mutta siihen tarvitaan kielen laajennuksia tai muita ulkoisia työkaluja.
ReST:in tavoitteena oli alunperin määritellä standardisoitu tapa ilmaista rakennetta erityisesti Pythonin lähdekoodiin kirjoitetuissa dokumentaatioriveissä sekä myös muissa erillisissä tekstitiedostoissa. Kielen suunnittelutavoitteet ovat seuraavat [16]:
• Luettavuus. Tekstin tulisi olla helposti luettavaa jo ennen kuin se on muutettu haluttuun formaattiin.
• Mahdollisimman yksinkertaiset tunnisteet. Eniten käytettävät tunnisteet tulisi olla kaikista yksinkertaisimpia.
17
• Syntaksin yksiselitteisyys.
• Intuitiivinen. Syntaksin tulee olla selvää ja helposti muistettavissa.
• Helppo käyttää millä tahansa tekstieditorilla
• Skaalautuvuus. Pitkienkin dokumenttien toteuttaminen tulee olla mahdollisimman helppoa
• Kielen tulee tarjota tarpeeksi ominaisuuksia hyvän dokumentin tekoon.
• Kielineutraali. Dokumentteja pystytään toteuttamaan englannin kielen lisäksi millä muulla tahansa kielellä
• Mahdollisuus laajennuksiin. Valmiiden ominaisuuksien lisäksi kieli tarjoaa yksinkertaisen syntaksin ja rajapinnan, jonka avulla voidaan lisätä uusia ominaisuuksia.
• Kielellä voi tuottaa dokumentteja useisiin eri formaatteihin.
3.2 Staattisten sivujen generointi
Verkkosivut voidaan jaotella dynaamisiin ja staattisiin sivuihin. Useimmiten tapa, jolla palvelin jakaa sivut niitä pyytäville käyttäjille, määrittää onko verkkosivut staattiset vai dynaamiset. Eli esimerkiksi sivunäkymät eivät välttämättä ole täysin muuttumattomia staattistenkaan sivujen tapauksessa, vaan ne voivat sisältää esimerkiksi JavaScriptillä tehtyjä animaatioita. Staattisten sivujen tapauksessa palvelimella on valmiina jokainen sivunäkymä,
Verkkosivut voidaan jaotella dynaamisiin ja staattisiin sivuihin. Useimmiten tapa, jolla palvelin jakaa sivut niitä pyytäville käyttäjille, määrittää onko verkkosivut staattiset vai dynaamiset. Eli esimerkiksi sivunäkymät eivät välttämättä ole täysin muuttumattomia staattistenkaan sivujen tapauksessa, vaan ne voivat sisältää esimerkiksi JavaScriptillä tehtyjä animaatioita. Staattisten sivujen tapauksessa palvelimella on valmiina jokainen sivunäkymä,