Planning and documentation

Good documentation is the difference between remembering how things work and getting stuck at 11 PM on a Sunday because the server is down and no one remembers how it was set up. Documentation may not be the most exciting part of IT operations, but it is one of the most important.

Why Document?

Types of Documentation in IT Operations

Det finnes mange typer dokumentasjon som er viktig i IT-drift. God dokumentasjon er avgjørende for å sikre stabil drift, rask feilsøking og effektiv kunnskapsdeling. Her er noen vanlige typer:

• Systemdokumentasjon: Beskriver systemarkitektur, komponenter, konfigurasjon og integrasjoner.
• Driftshåndbøker: Detaljerte instruksjoner for daglig drift, inkludert oppstart, nedstengning, overvåking og vedlikehold.
• Prosedyrer for hendelseshåndtering: Steg-for-steg beskrivelser av hvordan man håndterer ulike typer hendelser og feil.
• Katastrofeplaner: Beskriver hvordan man gjenoppretter IT-tjenester etter en større hendelse eller katastrofe.
• Sikkerhetsdokumentasjon: Retningslinjer og prosedyrer for å sikre IT-systemer og data.
• Brukerdokumentasjon: Hjelp og veiledning for sluttbrukere av IT-systemer.
• Kode dokumentasjon: Kommentarer og beskrivelser i kildekoden for å forklare funksjonalitet og logikk.

God dokumentasjon bør være:

• Oppdatert: Reflektere den faktiske tilstanden til systemene og prosessene.
• Klar og konsis: Lett å forstå og bruke.
• Tilgjengelig: Lett å finne for de som trenger den.
• Relevant: Fokusert på det som er viktig for IT-drift.

Mangelfull dokumentasjon kan føre til lange nedetider, økte kostnader og sikkerhetsrisiko. Derfor er det viktig å prioritere dokumentasjon som en del av IT-driften.

Network Diagram

A network diagram shows the physical and/or logical structure of the network. It can range from a simple sketch to a detailed diagram with VLANs, IP addresses, and firewall rules.

A good network diagram should include:

• All network devices (switches, routers, firewalls, access points)
• VLAN structure with subnet
• IP addresses for important devices (servers, gateway)
• Connections between devices

IP Plan

An IP plan is an overview of how IP addresses are distributed in the network. It helps you stay organized and avoid conflicts (two devices with the same address).

Example:

Static addresses:

Checklists

Checklists ensure that nothing is forgotten. They are especially useful for tasks you do less frequently, such as setting up a new server or conducting a security review.

Example: Checklist for new Linux server:

• Install operating system (Debian/Ubuntu)
• Update all packages (sudo apt update && sudo apt upgrade)
• Create user with sudo access
• Disable root login via SSH
• Configure firewall (ufw)
• Install necessary software
• Set up backup
• Document the server in the IP plan
• Test that the service works

Change Documentation

Each time you make a change in a production environment (server, network, service), you should document it. A simple log may be sufficient:

## Endringslogg

### 2026-04-14 - Oppgradert Nginx
- **Hva:** Oppdatert Nginx fra 1.24 til 1.26
- **Hvorfor:** Security update (CVE-2025-XXXX)
- **Hvem:** Ola
- **Resultat:** OK, no downtime

### 2026-04-10 - Nytt VLAN for IoT
- **Hva:** Opprettet VLAN 40 for IoT-enheter
- **Hvorfor:** Isolate IoT from the rest of the network
- **Hvem:** Kari
- **Resultat:** OK, all printers moved to VLAN 40

Operational Documentation

Operational documentation describes how a system functions in its current state:

Tools for Documentation

Task 1 - Create a Simple Network Diagram

Use draw.io (free) to draw the network at home or at school:

1. Start with the internet connection and the router
2. Add switches and access points
3. Draw in servers, PCs and other devices
4. Write in IP addresses where you know them

It doesn’t need to be perfect. The point is to start thinking visually about the network.

Task 2 - Create Your Own Checklist

Think of something you do regularly with IT (e.g., setting up a new VM, installing a development machine, or configuring VS Code). Write a checklist for the process:

• What are all the steps?
• What do you most often forget?
• Can you simplify any steps?

Save it in a Markdown document so you can use it next time.

Task 3 - Document one of your services

Choose a service you have set up (a VM, a Docker container, a web server) and write a short operational documentation:

• What does the service do?
• How do you start/stop it?
• What is the IP address and port?
• Is there a backup?

Write it in Markdown and put it in a Git repository.

Summary

• Documents for your future self: Write as if you are explaining to someone who knows nothing
• Network diagrams and IP plans provide an overview of the infrastructure
• Checklists ensure that nothing is forgotten during repetitive tasks
• Changelogs track what was done, when and by whom
• Operational documentation describes how the systems work today
• Use Markdown + Git for simple, version-controlled documentation