Torstaina, 20.1.2022

Dokumentointiin panostaminen kannattaa

Jokaisen yrityksen tulisi dokumentoida toimintansa. Toimivien operointimanuaalien avulla varmistutaan siitä, että tieto säilyy saatavilla, vaikka avainhenkilöt katoaisivat maan päältä.

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.

The Ultimate List of the Best Markdown Editors to Use in 2021
Markdown-työkalut ovat käyttöliittymiltään yleensä hirveitä.

√Ą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:

  1. Käytettävyys kuin unelma. Dokumentaation lisääminen ja muokkaaminen pitäisi olla maailman helpointa ja sujuvinta.
  2. 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.
  3. Datan omistaminen. Tiedon pitää pysyä ultimaattisesti meillä, vaikka muokkaus tapahtuisi muualla. Minimissään tiedon piti pystyä synkronoimaan esimerkiksi GitHubiimme.
  4. 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.
  5. Tuki koodisnipeteille. Helppo koodinpätkien ja komentojen lisääminen sekä niiden kopiointi yhdellä klikkauksella leikepöydälle pitäisi olla mahdollista.
  6. Asiakaspalvelu, joka reagoi ja ottaa palautteen huomioon.
GitBookissa dokumentaation muokkaaminen ja lisääminen on yhtä juhlaa.

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, kirjau