Asiantuntija tietää hyvin oman työnsä. Kun alan hommia on tullut tehtyä pidempään, unohtaa liian helposti, että töitä tekee joku muukin. Päähän mahtuu paljon tietoa ja rutiineja, jotka saattavat olla itselleen itsestäänselvyyksiä, mutta muille täysi mysteeri. Siksi asioiden dokumentointi on äärimmäisen tärkeää, kun töitä tekee porukassa.
Duden ensimmäiset neljä toimintavuotta koostuivat asiantuntijoista, jotka osaavat hommansa. Sittemmin porukkaan on tullut lisää tyyppejä ja meitä on vuonna 2022 vähintään seitsemän. Dokumentaatiota aloitettiin kirjoittamaan aktiivisemmin viidennen tekijän astuessa taloon vuonna 2018. Silloin aloitettiin kirjoittamaan dokumentaatiota oikeasti ihan siltä varalta, että ehkä joskus tulee taas lisää tyyppejä, jotka voivat lähteä tekemään suoraan, ilman että pitää kädestä pitäen kertoa 100% alusta loppuun uudestaan. Dokumentaatiota testattiin ja ehostettiin tekemisen mukana. Se ei kuitenkaan itsessään riittänyt, sillä yhä liikaa jäi kirjoittamatta ylös.
Jossain kohtaa huomattiin, että erityisesti tekninen dokumentaatio oli puutteellinen. Työn aloittaminen ja päivärutiinin edellyttämät asiat ovat olleet vuosia kirjoitettuna auki Handbookissamme, mutta kaikki yksityiskohdat ja nippelitiedot olivat hujan hajan GitHubimme README.md-tiedostoissa tai Wikeissä, erinäisissä Google Docseissa, Simplenote-muistioissa, projektityökaluissa, Slackissa ja mikä pahinta – yksittäisten ihmisten päissä, jos sielläkään.
Erityisesti palvelinhommat ovat olleet allekirjoittaneen CTO:n ja bäkkimestari-sysadmin-Wahalahden intohimona. Jokaisessa palvelinasennuksessa on sisäänkirjoitettua “tämä pitää vain tietää” -matskua, jota sitten on kirjoiteltu ties minne, yleensä txt ja md-tiedostoihin jonnekin pilvipalvelun tarjoamaan massamuistitilaan. Perusprosessit ovat olleet jossain step-by-step, mutta paljon on myös googlailtu, kun yksi ihmispää ei vain yksinkertaisesti muista asioita, jotka tehdään kerran pari vuodessa.
Vuonna 2021 otimme dokumentaation oikeasti tosissaan. Päätimme koota kaiken tiedon yhteen paikkaan.
Se onnistui. Tai ainakin lopulta.
“Mikä se yksi juttu oli? Missä projektissa käytettiin tätä? Muistatko? Ihan kielen päällä!”
Otimme käyttöön Cacher-nimisen palvelun. Tuntui fantsulta, että snipetit sai myös käyttöön koodieditorissaan näppäinyhdistelmällä. Kokosimme kaiken mahdollisen firman sisäisen teknisen tiedon Cacheriin, kunnes se oli täynnä hienoilla kategorioilla ja väreillä varustettuja muistiinpanoja ja tiedostoja. Kokosimme työkaluun myös kokonaisia Gutenberg-lohkoja.
Se oli kivaa niin kauan kuin sitä kesti. Yleensä oikea työkalu löytyy vasta toisella, tai kolmannella käyttöönotolla. Valinnat konkretisoituvat työkalujen toimimattomuuden myötä. Cacherissa oli ärsyttäviä bugeja ja huomasimme, että se tärkein eli haku ei toiminutkaan riittävän hyvin. Kun dokumentteja ja snippettejä alkoi olemaan satoja, Cacher haki liikaa. Hakusanoja piti tarkennella ja sitten ei löytynytkään mitään. Olisi varmaan pitänyt osata säännöllisiä lausekkeita (regular expressions), jotta olisi löytänyt heti tarvitsemansa. Ei jatkoon.
Cacher oikeastaan vain eskaloitti samoja ongelmia, joita meillä oli aikaisemmin. Nyt dokumentaatiota oli samassa paikassa, mutta dokkarit olivat hujan hajan.
Huomasimme myös lopulta, että emme käytä editori-integraatioita, koska ne pullauttavat liian ison läjän koodia mukaan. Meidän on kuitenkin aina käytävä katsomassa, mitä mikäkin snippetti pitää sisällään. Ja joskus tarvitsemme siitä vain osan. Ei ole itua hakea liikaa koodia dokkarista “sokkona”.
Syytän myös kökköä käyttöliittymää. Laitoin jatkuvalla syötöllä palautetta, joihin ei vastattu koskaan. Copy-pastet eivät toimineet, muokkailu oli kankeaa, jatka listaa… Alussa kaikki vaikutti niin pirun hyvältä ja taas kävi näin.
Markdown on surkea tapa kirjoittaa dokumentaatioita
Vuonna 2004 kehitetty Markdown on ollut dokumentointityökalujen pohjana kohta toista vuosikymmentä. Markdown on nykyään käytössä kaikkialla muuallakin kuin pelkästään koodareiden muistiinpanoissa. Jos käytät WordPressiä, testaapas huviksesi lisätä uutta artikkelia, laittaa tyhjän rivin alkuun kaksi risuaitaa (siis näin: ##) ja painaa välilyöntiä. Tämän pitäisi muodostaa h2-otsikon. Markdownissa otsikot muodostuvat risuaidoilla, boldaukset tähdillä, kursiivit alaviivalla ja niin edelleen. Kyseessä on helpompi merkkauskieli kuin HTML, mutta merkkauskieli yhtä kaikki. Koodareilta koodareille.
Markdown-työkaluissa on myös ärsyttävä tapa pitää muokkausnäkymä ja “esikatselu-näkymä” erillään toisistaan. Yleisimmin käyttöliittymät toimivat kökösti kahdessa eri paneelissa, jossa teksti on omassaan ja Markdown-koodi omassaan.
Älä käsitä väärin, Markdown ei ole itsessään huono valinta. Markdown on loistava silloin kun pitää kirjoittaa yksittäinen tiedosto ja säilöä se jonnekin. Se on myös loistava silloin kun muokattavuus on priimaa (live-esikatselu). Enimmäkseen Markdownin kankeus johtuu kankeista työkaluista. Typora ja Nota yrittävät ratkaista tätä ongelmaa ja Notaa käytänkin aktiivisesti puhtaiden .md-tiedostojen muokkailuun. Simplenotessa on muunmuassa ikuisuustiketti, jossa arvotaan yhä kolmatta vuotta pitäisikö Markdownin live-esikatselu ottaa käyttöön, jolloin päästäisiin eroon erillisestä muokkausnäkymästä. Mielestäni pitäisi.
Tekstin pitää näyttää hyvältä, jotta sitä on mielekästä kirjoittaa. Tekstin pitää olla helppolukuista ja selkeää myös kirjoittaessa. Koodieditorissa kirjoitetaan koodia, jolloin monospace-fontit pääsevät oikeuksiinsa. Koodieditorissa en kuitenkaan kirjoittaisi yhtä koodiriviä pidempää dokumentointia tai kokonaista blogiartikkelia tai kirjaa.
Kun kirjoittaa dokumentaatiota, pitää tykätä sekä työstään että kirjoittamisesta. Jotta kirjoittaminen olisi mukavaa, sen pitää olla mahdollisimman vaivatonta. Markdown on valitettavasti kuin kirjoittaisi koodia. Koodarina tietysti tykkään koodata, mutta olen myös kirjoittaja. Silloin kun kirjoitan, haluan keskittyä puhtaasti pelkkään tekstiin. Tekstin pitää näyttää tekstiltä, tuntua tekstiltä ja olla tekstiä. EI koodia. Boldaukset saisi tulla Macissa cmd + B:llä ja kursiivit cmd + I:llä, kuten ne tulevat Google Docsissa ja kaikkialla muuallakin.
Vanha Handbookimme toimi täysin Markdownilla, mutta sen tuottaminen WordPressillä erinäisten lisäreiden avulla ja synkronoiminen GitHubiin oli sen verran työlästä, että arkistoimme koko roskan. Muutimme jo pari vuotta sitten koko dokumentaation HTML-pohjaiseksi, jolloin se jäi hiljalleen päivittämättä ja tieto vanheni nopeasti. Ei kukaan jaksa erikseen kirjautua WordPressiin ja lähteä koodaamaan HTML:ää, jos jotain pitää saada nopeasti ylös kesken työn tohinan.
Vaikka löytyisi miten hyvä Markdown-editori, tiedostot ovat kuitenkin tiedostoja, ja yksittäisinä läjässä Drivessä, Dropboxissa, GitHubissa tai vastaavassa, niistä ei ole mitään hyötyä, kun niitä pitää kuitenkin etsiä ja pitää ajan tasalla. Muokkaamisen ja kokonaisuuden hallittavuuden pitää olla helppoakin helpompaa.
Oli aika tarkastella asiaa vielä uudemman kerran.
Dokumentityökalujen joukosta löytyi helmi
Kun loppuvuonna 2021 ajoitimme dokumentaation uudistamisen alkuvuodelle 2022, lähdin vuosittaisella Deviretriitillämme™ kahlaamaan jälleen dokumentointipalveluita läpi. Kävin läpi kymmeniä, joista osui kohdalle GitBook. Avoimen lähdekoodin Markdown-editoria tarjoavana firmana GitBook tarjoaa nykyisin SaaS-palveluna alustaa, jolla voi tehdä handbookeja, tietopankkeja ja dokumentaatioita. Kuulosti alustavasti juuri meille sopivalta.
Kriteerejämme työkalulle olivat:
- Käytettävyys kuin unelma. Dokumentaation lisääminen ja muokkaaminen pitäisi olla maailman helpointa ja sujuvinta.
- Tuki useammalle Handbookille. Totesimme, että tarvitsemme yhteensä neljä handbookia: Yrityksen yleinen handbook (tällainen meillä on aina ollutkin osoitteessa handbook.dude.fi), tekninen sisäinen handbook, avoimen lähdekoodin Air-tuoteperheen handbook ja julkinen koodaustandardien handbook). Näitä pitäisi pystyä hallitsemaan samasta paikasta ja linkkailemaan keskenään.
- Datan omistaminen. Tiedon pitää pysyä ultimaattisesti meillä, vaikka muokkaus tapahtuisi muualla. Minimissään tiedon piti pystyä synkronoimaan esimerkiksi GitHubiimme.
- Markdown-tuki. Ohjelmiston pitää tuottaa tiedostot nykyaikaisessa Markdown-muodossa. Vaikka äsken vähän parjasin Markdownia, se on silti yhteensopivin kaikkialla muualla ja sen avulla erityisesti koodinpätkien dokumentointi tuottaa suurta iloa. HTML tai LaTeX ei ollut vaihtoehto.
- Tuki koodisnipeteille. Helppo koodinpätkien ja komentojen lisääminen sekä niiden kopiointi yhdellä klikkauksella leikepöydälle pitäisi olla mahdollista.
- Asiakaspalvelu, joka reagoi ja ottaa palautteen huomioon.
Kaikki muut bonusta. GitBook oli kahlatuista työkaluista ainoa, joka täytti kaikki kriteerit. Siinä ei ollut mitään ylimääräistä. Ainoana hieman häiritsi isohko “Powered by GitBook”-banneri. Kysyin tarjousta Enterprise-tason tilistä, jolla sen olisi saanut pois, mutta 500 euroa kuukaudessa bannerin poistamisesta olisi hieman liikaa. Joten elämme sen kanssa. Mainostan hyvää palvelua mielelläni.
Hyvä työkalu säästää aikaa ja vaivaa
On ollut aikoja, jolloin olisimme SaaS-palvelun sijasta kikkailleet jonkun Docusaurus tai Jekyll-tyyppisen open source -härpäkkeen pystyyn ja yrittäneet palloilla .md-tiedostojen kanssa GitHub-maailmassa. Moni ei ehkä tiedä, mutta meillä oli oma “cooking book”, keittokirja koodille. GitHubin ja tiedostojen kautta päivittely on kuitenkin vaivalloista, mm. aiemmin mainituista syistä.
Valmiin SaaS-palvelun käyttäminen ei syö uskottavuuttamme avoimen lähdekoodin saralla, sillä meillä on silti suurin osa tekemisestämme ja koodistamme kaiken kansan nähtävillä. Ja nämäkin handbookit (paitsi sisäiset tekniset manuaalit) synkronoituvat julkisesti GitHubiin, kaupallisesta GitBook-pilvisovelluksesta huolimatta. Olihan datan omistaminen yksi tärkeimmistä kriteereistämme.
Nykyään ei enää jaksa lähteä säätämään asioita päivätolkulla, vaan haluaa keskittyä pelkkään puhtaaseen tuottavaan tekemiseen ilman ylimääräistä tilpehööriä. Dokumentaation voi tehdä itselleen vaivalloiseksi – tai helpoksi hyvän työkalun avulla. Me valitsimme jälkimmäisen.
Uusi firman virallinen handbook kääntyy pian osoitteesta handbook.wip.dude.fi tuttuun osoitteeseen handbook.dude.fi, Air-tuoteperheen dokumentaatio täydentyy osoitteseeen docs.airwptheme.com pikkuhiljaa, ja myös Duden koodistandardi-dokkari (DCS) tulee näkyviin myöhemmin. Loput ovat firman sisäisiä dokumentteja, jotka sisältävät mm. pitkiä tutoriaaleja, kuukausittaisen huoltoikkunan ajolistaa, kirjautumistietoja, asiakaskohtaisia tietoja, ynnä muita sellaisia asioita, joihin ei pääse valitettavasti julkisella osoitteella kiinni tietoturva- ja tietosuojasyistä.
Miten teillä dokumentoidaan firman asiat käytänteistä tekemiseen?
