Jokaisessa koodikannassa on dokumentaatiokansio, joka näytti loistavalta julkaisuviikollaan. Puolen vuoden kuluttua puolet sivuista kuvaa tuotteen versiota, jota ei enää ole, eikä uusimmista ominaisuuksista ole dokumentaatiota lainkaan.
Kyse on rakenteellisesta ja ajankäytöllisestä ongelmasta. Ymmärtäminen, miksi manuaalinen dokumentaatio rappeutuu ennustettavassa aikataulussa, on ensimmäinen askel dokumentaation todelliseen parantamiseen pysyvästi sen sijaan, että joka vuosi toteutettaisiin sama uudelleenkirjoitusprojekti. Tässä syyt, miksi perinteinen lähestymistapa kehittäjädokumentaatioon epäonnistuu jo suunnittelultaan, ja mikä todella katkaisee kierteen.
Dokumentaatiovelan ongelma: miten tiimit päätyvät siihen
Dokumentaatiovelka toimii kuin kuuluisampi serkkunsa tekninen velka, paitsi että se on vaikeampi nähdä. Koodissa tehty oikaisu aiheuttaa lopulta virheen, joka jonkun on korjattava. Vanhentunut dokumentti vain istuu hiljaa paikallaan ja on väärässä, eikä kukaan huomaa sitä ennen kuin uusi työntekijä seuraa sitä ja rikkoo jotain, tai tukipyyntö paljastaa, että asennusohje on neljän kuukauden ajan kuvannut vanhentunutta lippua.
Kaari on lähes aina sama. Julkaisuhetkellä dokumentaatio on perusteellista, koska tiimi on motivoitunut ja kokonaisuus on pieni. Kolme kuukautta ja viisi ominaisuusjulkaisua myöhemmin kaksi näistä ominaisuuksista on dokumentoitu, ja loput kolme ovat olemassa vain ne rakentaneiden ihmisten päässä. Siihen mennessä kun joku käy dokumentaation läpi, kuilu kirjoitetun ja toden välillä on kasvanut niin suureksi, että sen korjaaminen näyttää projektilta eikä tavalta.
Tämä ei ole myöskään hypoteettinen kustannus. Stack Overflown tutkimus havaitsi, että dokumentaatio kuluttaa jo noin 11 % kehittäjien työtunneista, ja GetDX arvioi , että insinöörit menettävät 3-10 tuntia viikossa etsiessään tietoa, joka pitäisi jo olla kirjoitettuna – tunteja, jotka eivät näy missään tiekartalla mutta katoavat silti todellisesta tuotoksesta.
Miksi manuaalinen dokumentaatio jää aina kehityksestä jälkeen
Koodimuutosten tekeminen on halpaa ja dokumentoiminen kallista. Yhden rivin korjaus nopeusrajoittimeen voi viedä viisi minuuttia kirjoittaa ja julkaista, mutta sen tarkka selittäminen – mikä muuttui, miksi ja mitä se tarkoittaa kenelle tahansa kyseistä päätepistettä kutsuvalla – vaatii todellista, keskeytyksetöntä kirjoitusaikaa, jota ei ole sprinteissä, jotka ovat jo täynnä muita sitoumuksia.
Jokainen commit on pieni, hiljainen päätöksentekokohta. Jonkun on huomattava, että muutos on tarpeeksi merkittävä dokumentoitavaksi, muistettava se ja löydettävä sitten aikaa sen tekemiseen. Manuaalinen dokumentaatio riippuu siitä, että kaikki nämä kolme asiaa tapahtuvat johdonmukaisesti jokaisen merkittävän muutoksen kohdalla. Riittää, että yksi niistä pettää silloin tällöin, ja velka alkaa kasautua.
Uskomus siitä, että siistin koodin pitäisi olla itsestään selittävää, ei auta. Hyvin nimetyt funktiot ja selkeä logiikka selittävät, mitä koodi tekee, sellaiselle, joka jo tuntee koodikannan sujuvasti. Se ei selitä miksi tai miksi juuri näin, miten sitä käytetään tai miten se sopii laajempaan järjestelmään. Juuri sellaista tietoa manuaalisen dokumentaation pitäisi tarjota ja juuri sitä tietoa ohitetaan, kun aika on kortilla.
Valmis kasvattamaan liiketoimintaasi?
Aloita ilmainen kokeilujakso tänään ja näe tulokset muutamassa päivässä.
Puutteellisen kehittäjädokumentaation 3 perimmäistä syytä
Yleisen “dokumentaatiomme on huonoa” -valituksen alla on kolme konkreettista, korjattavissa olevaa mekanismia:
- Omistajuus on hajautunut. Kun dokumentaatio on “kaikkien vastuulla”, se ei käytännössä ole kenenkään vastuulla. Ilman tiettyä henkilöä tai liipaisinta, joka on vastuussa tietyn dokumentin päivittämisestä, se jää sen varaan, joka sattuu huomaamaan sen olevan väärin – usein hämmentynyt uusi työntekijä tai turhautunut asiakas. Lisäksi tämä lähestymistapa levittää epäjohdonmukaista muotoilua, kieltä ja kirjoitustyylejä.
- Kustannus on epäsymmetrinen. Muutoksen kirjoittaminen on nopeampaa kuin kirjoittaa siitä muutoksesta tarkka selitys jollekin toiselle. Minkä tahansa aikapaineen alla tehtävä, joka kilpailee suoraan julkaisemisen kanssa, häviää.
- Liipaisinmekanismia ei ole. Useimmat tiimit eivät sido dokumentaation päivitystä konkreettiseen tapahtumaan, kuten yhdistettyyn pull requestiin tai julkaisuun. Ilman tätä liipaisinta dokumentaatioon tartutaan vain reaktiivisesti, sen jälkeen kun tukipyyntö tai perehdytyksen epäonnistuminen pakottaa asian esille – mikä tarkoittaa, että korjaus saapuu aina sen jälkeen, kun kustannus on jo maksettu.
Miten tekoäly sulkee koodin ja dokumentaation välisen kuilun
Tekoälypohjainen dokumentaatiokirjoittaja puuttuu suoraan näihin kolmeen syyhyn, koska se muuttaa taloudellista yhtälöä sen sijaan, että pyytäisi ihmisiä käyttäytymään toisin samoissa rajoitteissa.
FlowHuntin AI Documentation Writer etenee kolmen vaiheen kautta . Se analysoi ensin koodin, kääntää sitten logiikan ja jäsentää lopuksi tulostiedoston. Sinä annat lähdekoodin, pääohjelmointikielen, käyttötarkoituksen, kohdeyleisön ja mahdolliset muut tiedot, jotka katsot tarpeellisiksi tai joita lomake pyytää.
Lopullinen tuotettu dokumentti kattaa johdon yhteenvedon, toiminnalliset kyvykkyydet, teknisen arkkitehtuurin, logiikan kulun, keskeiset funktiot ja komponentit sekä käyttöohjeet.
Tämä prosessi korjaa kustannusten epäsymmetrian suoraan. Jos tarkan dokumentaation tuottaminen uudelleen ajantasaisesta koodista vie muutaman minuutin puolen päivän huolellisen kirjoittamisen sijaan, se lakkaa häviämästä prioriteettikamppailua koodin julkaisemista vastaan.
Se myös lieventää omistajuusongelmaa, sillä nopea ja vähän vaivaa vaativa prosessi on realistista antaa sen tehtäväksi, joka yhdistää muutoksen, sen sijaan, että joka kerta tarvittaisiin erillinen kirjoittaja mukaan. Pienten mutta aikaa vievien tehtävien siirtäminen pois kirjoittajilta antaa heille mahdollisuuden panostaa enemmän korkean panoksen sisältöön.
Liipaisinmekanismi on silti rakennettava tarkoituksella. FlowHunt ei seuraa repositoriotasi itsestään, mutta koska se on työnkulun automaatioalusta, työnkulku voidaan kytkeä webhookiin, joka laukeaa aina, kun dokumentoitua moduulia koskeva pull request yhdistetään.
Liity uutiskirjeellemme
Saa uusimmat vinkit, trendit ja tarjoukset ilmaiseksi.
Sellaisen dokumentaatiojärjestelmän rakentaminen, joka pysyy ajan tasalla
Dokumentaatiojärjestelmä, joka selviää ensimmäisiä kuukausia pidemmälle, tarvitsee muutakin kuin nopean tuottamisvaiheen. Toimiva silmukka näyttää tältä:
Liipaisin. Yhdistetty pull request tai uuden julkaisun valmistelu lähettää olennaisen lähdekoodin dokumentaatiokirjoittajalle, ja yleisö ja käyttötarkoitus on asetettu kyseiselle dokumenttityypille (API-viite, käyttöopas, sisäinen toimintaohje).
Tallenna se, mitä koodissa ei ole. Osa kontekstista ei koskaan päädy lähdekoodiin, kuten se, miksi käyttöönotto-skripti toimii niin kuin toimii – mikä yleensä on olemassa vain yhden insinöörin suullisena selityksenä. Tämä tieto kannattaa aina syöttää työkaluun koodin ohella. Selitys lisää kontekstia ja syvyyttä, mikä varmistaa inhimillisemmän ja yksilöidymmän sisällön tuottamisen.
Ristiintarkista ulkoinen konteksti, kun sillä on väliä. Tarkista ulkoisista lähteistä kaikki toimialastandardit, protokollat tai käytännöt, jotka kannattaa varmistaa. Tarkista uudelleen myös tekoälylle antamasi oma data, sillä se voi olla vanhentunutta.
Katselmoi ennen julkaisua. Järjestelmän tunteva henkilö varmistaa, että asennusvaiheet todella toimivat, tarkistaa, että mahdollinen perintökomponentti, jota tekoäly ei pystynyt päättelemään pelkästä koodista, on kuvattu oikein, ja varmistaa, että tuotos on luettavissa oikein kohdeyleisölleen.
Laukaise uudelleen seuraavan muutoksen yhteydessä. Voit määrittää uudelleentuottamisen aikataulun mukaan tai mukautetulla liipaisimella. Voit esimerkiksi saada silmukan toistumaan seuraavassa yhdistämisessä, mikä on paras tapa pitää koodin ja dokumentaation välinen kuilu pienenä.
Millaista hyvä kehittäjädokumentaatio todella on
Hyvää dokumentaatiota ei määrittele sen pituus tai viimeistely, vaan se, vastaako se kysymyksiin, joita lukijalla todella on, siinä järjestyksessä kuin hän ne esittäisi. Hyödyllinen rakenne kattaa:
- Mitä se tekee — lyhyt yhteenveto tarkoituksesta ja laajuudesta, jotta lukija voi yhdestä kappaleesta päätellä, onko hän oikeassa paikassa.
- Mitä se mahdollistaa — konkreettiset kyvykkyydet ja ominaisuudet, ei vain koodin toistoa.
- Miten se on rakennettu — riittävästi arkkitehtuurikontekstia (teknologiapino, komponentit, riippuvuudet), jotta joku voi järkeillä järjestelmästä, ei vain käyttää sitä.
- Miten se toimii — logiikan kulku ja keskeiset toiminnot selitettynä prosessina eikä luettelona funktioiden nimistä.
- Miten sitä käytetään — asennus-, määritys- ja käyttöohjeet kirjoitettuna sille, joka on todellinen lukija, ei sille, joka kirjoitti koodin.
Tämä on myös – ei sattumalta – lähellä sitä, mitä koodiin nojaava tuottamisprosessi luonnostaan tuottaa, sillä jokainen osio vastaa kysymystä, jonka todellinen lukija esittää, eikä osiota, jonka kirjoittaja koki velvollisuudekseen sisällyttää.
Dokumentaatiovelasta dokumentaatiopääomaksi
Dokumentaatiovelka ja dokumentaatio pääomana ovat samaa perusainesta – lähdekoodia ja organisaation tietämystä – kahdella eri ylläpitokustannusten tasolla. Heti kun dokumentin uudelleentuottaminen tulee niin halvaksi, että se kannattaa tehdä jokaisen merkittävän muutoksen yhteydessä, sama tieto, joka ennen rappeutui velaksi, alkaa karttua joksikin, johon tiimi voi luottaa.
Aloita paremman dokumentaation kirjoittaminen tekoälyllä ja katso, kuinka suuri osa nykyisestä dokumentaatiovelastasi on todella vain kustannusongelma, joka odottaa nopeampaa prosessia.
Täydelliset mekanismit siitä, miten taustalla oleva tuottamisprosessi toimii, löydät artikkelista miten tekninen dokumentaatio kirjoitetaan automaattisesti tekoälyllä , ja tietyistä dokumenttityypeistä, jotka tämä lähestymistapa kattaa hyvin, artikkelista viisi dokumenttityyppiä, jotka tekoäly kirjoittaa nopeammin .
