Tämä on konekäännetty teksti, joka saattaa sisältää virheitä!
Hyvä dokumentaatio on ero sen muistamisen välillä, miten asiat toimivat, ja sen välillä, että juututaan klo 23 sunnuntaina, koska palvelin on alhaalla eikä kukaan muista, miten se on asennettu. Dokumentaatio ei ehkä ole IT-toiminnan jännittävin osa, mutta se on yksi tärkeimmistä.
Miksi dokumentoida?
| Peruste | Selitys |
|---|---|
| Muisti | Et muista kaikkea kuuden kuukauden päästä, etkä tarvitsekaan |
| Yhteistyö | Muiden on voitava ymmärtää, mitä olet tehnyt, kysymättä sinulta |
| Vikojen korjaus | Kun jokin on vialla, on arvokasta tietää, mikä on normaalia |
| Uudelleenrakentaminen | Jos palvelin kaatuu, sinun on tiedettävä tarkalleen, miten se oli määritetty |
| Jäljitettävyys | Mitä muutettiin, milloin ja kenen toimesta? |
Kirjoita dokumentaatio “tulevaisuuden sinulle”
Paras nyrkkisääntö: kirjoita ikään kuin selittäisit itsellesi kuuden kuukauden päästä. Silloin voit olla varma, että sisällytät riittävästi yksityiskohtia ilman, että monimutkaistat asioita.
IT-toiminnan dokumentaatiotyypit
Dokumentasjon er en kritisk del av effektiv IT-drift. God dokumentasjon sikrer at systemer kan vedlikeholdes, feilsøkes og videreutvikles på en smidig måte. Uten tilstrekkelig dokumentasjon kan selv enkle endringer bli kompliserte og tidkrevende. Det finnes flere typer dokumentasjon som er relevante for IT-drift, og det er viktig å forstå forskjellen mellom dem.
Teknisk dokumentasjon
Teknisk dokumentasjon beskriver hvordan systemene er bygget opp og fungerer. Dette inkluderer arkitekturdiagrammer, databasemodeller, kodekommentarer og API-dokumentasjon. Teknisk dokumentasjon er primært rettet mot utviklere og systemadministratorer.
Brukerdokumentasjon
Brukerdokumentasjon er ment for sluttbrukere av systemene. Den beskriver hvordan systemene skal brukes, og inneholder ofte veiledninger, opplæringsmateriell og feilsøkingsinstruksjoner. God brukerdokumentasjon gjør det enkelt for brukerne å komme i gang med systemene og løse vanlige problemer selv.
Driftshåndbok
Driftshåndboken beskriver hvordan systemene skal driftes og vedlikeholdes i produksjon. Dette inkluderer informasjon om oppstart og nedstenging av systemer, overvåking, sikkerhetskopiering og gjenoppretting. Driftshåndboken er et viktig verktøy for driftspersonell og hjelper til med å sikre stabil og pålitelig drift.
Prosedyrebeskrivelser
Prosedyrebeskrivelser beskriver steg-for-steg hvordan spesifikke oppgaver skal utføres. Dette kan være alt fra hvordan man oppretter en ny bruker til hvordan man løser et bestemt problem. Prosedyrebeskrivelser er nyttige for å standardisere arbeidsprosesser og redusere risikoen for feil.
Verkkokartta
Verkkokartta näyttää verkon fyysisen ja/tai loogisen rakenteen. Se voi olla yksinkertainen luonnos tai yksityiskohtainen kaavio, jossa on VLAN-verkkoja, IP-osoitteita ja palomuurisääntöjä.
Hyvä verkkokartta tulisi sisältää:
- Kaikki verkkolaitteet (kytkimet, reitittimet, palomuuri, tukiasemat)
- VLAN-rakenne aliverkkoineen
- IP-osoitteet tärkeille laitteille (palvelimet, yhdyskäytävä)
- Yhteydet laitteiden välillä
IP-suunnitelma
IP-suunnitelma on yleiskatsaus siitä, miten IP-osoitteet on jaettu verkossa. Se auttaa sinua pitämään järjestyksen ja välttämään konflikteja (kaksi laitetta samalla osoitteella).
Esimerkki:
| VLAN | Nimi | Aliverkko | Yhdyskäytävä | DHCP-alue | Huomautukset |
|---|---|---|---|---|---|
| 10 | Hallinto | 10.0.10.0/24 | 10.0.10.1 | .100 - .200 | Rajoitettu pääsy |
| 20 | Työntekijät | 10.0.20.0/24 | 10.0.20.1 | .100 - .250 | |
| 30 | Opiskelijat | 10.0.30.0/24 | 10.0.30.1 | .100 - .250 | Vain internet |
| 50 | Palvelimet | 10.0.50.0/24 | 10.0.50.1 | Ei (staattinen) | Kiinteät IP-osoitteet |
Staattiset osoitteet:
| IP-osoite | Laite | Rooli |
|---|---|---|
10.0.50.10 | web-01 | Nginx |
10.0.50.11 | db-01 | PostgreSQL |
10.0.50.12 | monitoring-01 | Grafana + Loki |
10.0.50.20 | proxmox | Hypervisor |
Tarkistuslistat
Tarkistuslistat varmistavat, ettei mitään unohdeta. Ne ovat erityisen hyödyllisiä harvemmin tehtäviin tehtäviin, kuten uuden palvelimen pystyttämiseen tai tietoturvatarkastuksen suorittamiseen.
Esimerkki: Tarkistuslista uudelle Linux-palvelimelle:
- Asenna käyttöjärjestelmä (Debian/Ubuntu)
- Päivitä kaikki paketit (
sudo apt update && sudo apt upgrade) - Luo käyttäjä sudo-oikeuksilla
- Poista root-sisäänkirjautuminen käytöstä SSH:n kautta
- Määritä palomuuri (
ufw) - Asenna tarvittava ohjelmisto
- Aseta varmuuskopiointi
- Dokumentoi palvelin IP-suunnitelmassa
- Testaa, että palvelu toimii
Muutoshistoria
Aina kun teet muutoksen tuotantoympäristössä (palvelin, verkko, palvelu), sinun tulisi dokumentoida se. Yksinkertainen loki voi riittää:
## Endringslogg
### 2026-04-14 - Oppgradert Nginx
- **Hva:** Oppdatert Nginx fra 1.24 til 1.26
- **Miksi:** Turvapäivitys (CVE-2025-XXXX)
- **Kuka:** Ola
- **Tulos:** OK, ei käyttökatkosta
### 2026-04-10 - Nytt VLAN for IoT
- **Hva:** Opprettet VLAN 40 for IoT-enheter
- **Miksi:** Eristää IoT:n muusta verkosta
- **Kuka:** Kari
- **Tulos:** OK, kaikki tulostimet siirretty VLAN 40:een
Käytä Git:iä!
Jos kirjoitat dokumentaation Markdown-tiedostoihin (suositeltavaa), voit versiohallita niitä Gitillä. Silloin sinulla on automaattinen historia kaikista muutoksista, ja voit nähdä kuka muutti mitä ja milloin.
Käyttödokumentaatio
Käyttödokumentaatio kuvaa, miten järjestelmä toimii nykyisessä tilassaan:
| Mikä | Esimerkki |
|---|---|
| Järjestelmäarkkitehtuuri | “Ajamme Proxmoxia 3 VM:llä: web, db, monitoring” |
| Käyttötiedot | “SSH portin 22 kautta, vain VPN:stä” |
| Varmuuskopiointirutiinit | “Päivittäinen varmuuskopio klo 02:00 ulkoiselle levylle” |
| Yhteystiedot | “Ongelmatilanteissa, ota yhteyttä Ola (admin)” |
| Palautusvaiheet | “Käynnistä uudelleen: sudo systemctl restart nginx“ |
Työkalut dokumentaatioon
| Työkalu | Mihin sitä käytetään | Edut |
|---|---|---|
| Markdown | Tekstiä yksinkertaisella muotoilulla | Kevyt, siirrettävä, toimii Gitin kanssa |
| draw.io | Kaaviot ja verkkokartat | Ilmainen, visuaalinen, vie kuvaksi |
| Obsidian | Muistiinpanosovellus Markdownilla ja linkityksellä | Hyvä henkilökohtaiseen tietopankkiin |
| MkDocs | Julkaise Markdown verkkosivustona | Ammattimainen dokumentaatio |
| Git/GitHub | Dokumentaation versionhallinta | Historia, yhteistyö, varmuuskopio |
Tehtävä 1 – Luo yksinkertainen verkkokartta
Käytä draw.io (ilmainen) piirtääksesi verkon kotona tai koulussa:
- Aloita internet-yhteydestä ja reitittimestä
- Lisää kytkimet ja tukiasemat
- Piirrä palvelimet, tietokoneet ja muut laitteet
- Kirjoita IP-osoitteet, jos tiedät ne
Sen ei tarvitse olla täydellinen. Pääasia on alkaa ajatella verkkoa visuaalisesti.
Tehtävä 2 – Luo oma tarkistuslista
Mieti jotain, mitä teet säännöllisesti IT:n kanssa (esim. uuden VM:n pystyttäminen, kehityskoneen asentaminen tai VS Coden konfigurointi). Kirjoita prosessille tarkistuslista:
- Mitkä ovat kaikki vaiheet?
- Mitä unohdat useimmiten?
- Voitko yksinkertaistaa joitain vaiheita?
Tallenna se Markdown-dokumenttiin, jotta voit käyttää sitä seuraavalla kerralla.
Tehtävä 3 – Dokumentoi yksi palveluistasi
Valitse palvelu, jonka olet pystyttänyt (VM, Docker-kontti, web-palvelin) ja kirjoita lyhyt käyttöohje:
- Mitä palvelu tekee?
- Kuinka käynnistät/pysäytät sen?
- Mikä on IP-osoite ja portti?
- Onko olemassa varmuuskopioita?
Kirjoita se Markdownilla ja lisää se Git-repositorioon.
Yhteenveto
- Dokumentoi tulevaisuuden sinulle: Kirjoita ikään kuin selittäisit jollekulle, joka ei tiedä mitään
- Verkkokartat ja IP-suunnitelmat antavat yleiskuvan infrastruktuurista
- Tarkistuslistat varmistavat, ettei mitään unohdeta toistuvissa tehtävissä
- Muutoslokit seuraavat mitä tehtiin, milloin ja kenen toimesta
- Käyttöohjedokumentaatio kuvaa, miten järjestelmät toimivat nykyään
- Käytä Markdown + Git -ohjelmaa helppoon, versiohallittuun dokumentaatioon