Dokumentointi on tärkeämpää kuin itse automaatio

Automaatio toimii. Kirjoitit sen puoli vuotta sitten. Nyt se hajoaa klo 2 yöllä ja sinä olet lomalla.

Kollegasi avaa skriptin. Muuttujat on nimetty lyhenteillä, joita vain sinä ymmärrät. Kommentteja ei ole. Jossain on kovakoodattuja arvoja, joiden alkuperästä ei ole tietoa. Credentials-tiedostoon viittaava polku on sinun koneeltasi.

Tämä on todellinen hinta dokumentoimattomasta automaatiosta.

Miksi dokumentointi jää tekemättä

Koska automaatio toimii. Kun se on valmis ja testattu, tuntuu, ettei dokumentoinnille ole kiire. Ja myöhemmin ei koskaan tule, koska muita asioita on enemmän.

Toinen syy on se, että rakentaja ymmärtää kaiken. Muuttujanimien lyhenteet, kovakoodatut arvot, reunatapausten logiikka. Kaikki on selvää sille, joka rakensi.

Kenellekään muulle se ei ole selvää.

Mitä hyvä dokumentaatio tarkoittaa käytännössä

Hyvä dokumentaatio ei tarkoita kirjaa. Se tarkoittaa kolmea asiaa.

Mitä tämä tekee, sanoilla, joita kollega ymmärtää ilman teknistä taustaa. Ei "skripti iteroi AD-ryhmän jäsenet", vaan "skripti lähettää viikoittaisen yhteenvedon IT-tuen tikettijonosta tiimin sähköpostiin".

Miksi tämä on rakennettu niin kuin on rakennettu. Reunatapaukset, joita ei näe koodista. Miksi siellä on se 30 sekunnin viive? Miksi tietty käyttäjäryhmä ohitetaan? Nämä päätökset ovat skriptin kirjoittajan päässä, eivät koodissa.

Mitä täytyy tarkistaa, jos tämä hajoaa. Lokien sijainti, kriittiset muuttujat, ulkoiset riippuvuudet. Mitä palvelua pitää tarkistaa ensin? Mikä API-avain vanhenee milloin?

Käytännön tapa toteuttaa

Neljä riviä kommenttia skriptin alussa vie minuutin. Se säästää kollegan kolme tuntia puolen yön hätätilanteessa.

# Nimi: Tikettijono-yhteenveto
# Tarkoitus: Lähettää viikoittaisen yhteenvedon avoimista tiketeistä tiimille
# Ajastettu: Maanantaisin klo 08:00, Task Scheduler / Palvelin: srv-auto01
# Riippuvuudet: ServiceDesk API (avain: secrets/servicedesk-api.key), Teams webhook
# Yhteyshenkilö: Joonas L. jos ongelmia
# Viimeksi muokattu: 2026-05-14

Lisäksi: tallenna skripti versionhallintaan. Ei "final_v3_OIKEA.ps1", vaan Git. Historiasta näkee, mitä muutettiin ja miksi.

Dokumentaatio on osa automaation ylläpitoa

Automaatio ilman dokumentaatiota on ajastettu ongelma. Ehkä se iskee kuuden kuukauden päästä, ehkä kahden vuoden. Mutta jos kukaan muu ei pysty ylläpitämään sitä, se ei ole automaatio. Se on henkilöriski.

Parasta dokumentaatiota on se, joka kirjoitetaan samaan aikaan kuin koodi. Ei sen jälkeen, ei "myöhemmin".

Haluatko tarkistaa automaatioidenne dokumentaatiotason? Otetaan yhteyttä.