This is a machine-translated text that may contain errors!
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?
| Reason | Explanation |
|---|---|
| Memory | You won’t remember everything in six months, and you don’t need to |
| Collaboration | Others must be able to understand what you have done without asking you |
| Troubleshooting | When something is wrong, it is invaluable to know what is normal |
| Rebuilding | If a server dies, you need to know exactly how it was set up |
| Auditability | What was changed, when and by whom? |
Write documentation for “future you”
The best rule of thumb: write as if you are explaining it to yourself in six months. That way, you are guaranteed to include enough detail without overcomplicating things.
Types of documentation in IT operations
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:
| VLAN | Name | Subnet | Gateway | DHCP-range | Notes |
|---|---|---|---|---|---|
| 10 | Administration | 10.0.10.0/24 | 10.0.10.1 | .100 - .200 | Limited access |
| 20 | Employees | 10.0.20.0/24 | 10.0.20.1 | .100 - .250 | |
| 30 | Students | 10.0.30.0/24 | 10.0.30.1 | .100 - .250 | Internet only |
| 50 | Servers | 10.0.50.0/24 | 10.0.50.1 | None (static) | Fixed IP addresses |
Static addresses:
| IP Address | Device | Role |
|---|---|---|
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 |
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:
## Changelog
### 2026-04-14 - Upgraded Nginx
- **What:** Updated Nginx from 1.24 to 1.26
- **Why:** Security update (CVE-2025-XXXX)
- **Who:** Ola
- **Result:** OK, no downtime
### 2026-04-10 - New VLAN for IoT
- **What:** Created VLAN 40 for IoT devices
- **Why:** Isolate IoT from the rest of the network
- **Who:** Kari
- **Result:** OK, all printers moved to VLAN 40
Use Git!
If you write the documentation in Markdown files (recommended), you can version control them with Git. This way, you automatically have a history of all changes, and you can see who changed what and when.
Operational Documentation
Operational documentation describes how a system functions in its current state:
| What | Example |
|---|---|
| System Architecture | “We are running Proxmox with 3 VMs: web, db, monitoring” |
| Access Information | “SSH via port 22, only from VPN” |
| Backup Routines | “Daily backup at 02:00 to external disk” |
| Contact Information | “In case of problems, contact Ola (admin)” |
| Recovery Steps | “Restart with: sudo systemctl restart nginx“ |
Tools for Documentation
| Tool | What it is used for | Benefits |
|---|---|---|
| Markdown | Text with simple formatting | Lightweight, portable, works with Git |
| draw.io | Diagrams and network maps | Free, visual, export to image |
| Obsidian | Note app with Markdown and linking | Good for personal knowledge base |
| MkDocs | Publish Markdown as a website | Professional documentation |
| Git/GitHub | Version control of documentation | History, collaboration, backup |
Task 1 - Create a Simple Network Diagram
Use draw.io (free) to draw the network at home or at school:
- Start with the internet connection and the router
- Add switches and access points
- Draw in servers, PCs and other devices
- 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