This here’s a machine-translated text that might contain errors!
Good documentin’ is the difference between rememberin’ how things work and bein’ stuck at 11 PM on a Sunday ‘cause the server’s down and nobody remembers how it was set up. Documentin’ might not be the most excitin’ part of IT operations, but it’s one of the most important.
Why Document?
| Reason | Explanation |
|---|---|
| Memory | You won’t recall everything in six months, and ya don’t need to |
| Collaboration | Others gotta understand what you done without askin’ ya |
| Troubleshooting | When somethin’s wrong, knowin’ what’s normal is priceless |
| Rebuildin’ | If a server kicks the bucket, you need to know exactly how it was set up |
| Auditability | What was changed, when, and by who? |
Write the documentation for “your future self”
The best rule of thumb: write like you’re explainin’ things to yourself six months down the trail. That way, you’re guaranteed to include enough details without makin’ things too complicated.
Kinds of Documentation in IT Operations
Network Map
A network map shows the physical and/or logical structure of the network. It can be anything from a simple sketch to a detailed diagram with VLANs, IP addresses, and firewall rules.
A good network map ought to include:
- All network gear (switches, routers, firewall, access points)
- VLAN structure with subnets
- IP addresses for the important pieces (servers, gateway)
- Connections between devices
IP Plan
An IP plan is a rundown of how IP addresses are divvied up in the network. It helps ya keep things tidy and avoid ruckus (two contraptions 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 make shore nothin’ gets forgot. They’re mighty helpful for tasks ya don’t do too often, like settin’ up a new server or doin’ a security check-up.
Example: Checklist for a new Linux server:
- Install the operatin’ system (Debian/Ubuntu)
- Update all packages (
sudo apt update && sudo apt upgrade) - Create a user with sudo access
- Disable root login via SSH
- Configure the firewall (
ufw) - Install necessary software
- Set up backup
- Document the server in the IP plan
- Test that the service is workin’
Change Documentation
Every time ya make a change to a production environment (server, network, service), ya oughta document it. A simple log’ll do just fine:
## Change Log
### 2026-04-14 - Upgraded Nginx
- **What:** Updated Nginx from 1.24 to 1.26
- **Why:** Security fix (CVE-2025-XXXX)
- **Who:** Ola
- **Result:** OK, no downtime
### 2026-04-10 - New VLAN for IoT
- **What:** Created VLAN 40 for IoT critters
- **Why:** Keep IoT away from the rest of the ranch network
- **Who:** Kari
- **Result:** OK, all them printers moved to VLAN 40
Bruk Git!
If you’re writin’ them docs in Markdown files (highly recommended), you can keep ‘em under version control with Git. That way, you’ll automatically have a history of every single change, and you can see who changed what and when.
Runnin’ Docs
Runnin’ Docs tells ya how a system’s workin’ right now:
| What | Example |
|---|---|
| System Architecture | “We’re runnin’ Proxmox with 3 VMs: web, db, monitorin’” |
| Access Info | “SSH through port 22, only from the VPN” |
| Backup Routine | “Daily backup at 02:00 to an external disk” |
| Contact Info | “If ya got trouble, contact Ola (admin)” |
| Recovery Steps | “Restart with: sudo systemctl restart nginx“ |
Tools for Documentin’
| Tool | What it’s used for | Benefits |
|---|---|---|
| Markdown | Text with simple formatin’ | Light, portable, works with Git |
| draw.io | Diagrams and network maps | Free, visual, export to image |
| Obsidian | Note app with Markdown and linkin’ | Good for personal knowledge base |
| MkDocs | Publish Markdown as a website | Professional documentation |
| Git/GitHub | Version control of documentation | History, collaboration, backup |
Task 1 - Draw a Simple Network Map
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 on IP addresses where you know ‘em
It don’t need to be perfect. The point is to start thinkin’ visually ‘bout the network.
Task 2 - Make Yer Own Checklist
Think on somethin’ ya do regular with IT (like settin’ up a new VM, installin’ a development machine, or configurin’ VS Code). Write up a checklist for the process:
- What’s all the steps involved?
- What do ya most often forget?
- Can ya simplify any o’ them steps?
Save it in a Markdown document so ya can use it next time.
Task 3 - Document One o’ Yer Services
Pick a service ya done set up (a VM, a Docker container, a web server) and write a short runnin’ doc:
- What does this here service do?
- How do ya start ‘er up or shut ‘er down?
- What’s the IP address and port?
- Is there a backup, now?
Write it in Markdown and put it in a Git repository.
Summin’ It Up
- Docs for Yer Future Self: Write it like yer explainin’ to someone who don’t know a thing
- Network Maps and IP Plans give ya a clear view of the infrastructure
- Checklists make sure nothin’ gets forgot when doin’ the same tasks over and over
- Change Logs keep track of what was done, when, and by who
- Operational Documentation describes how the systems work today
- Use Markdown + Git for easy, version-controlled documentation