Avast ye! This be a machine-translated text, an’ it may contain errors, aye!
Good documentin’ be the difference ‘tween rememberin’ how things work an’ bein’ stuck at 11 o’clock on a Sunday ‘cause the server be down an’ no one remembers how it were set up. Documentin’ may not be the most excitin’ part o’ IT operations, but ‘tis one o’ the most important.
Why Document, Aye?
| Reason | Explanation |
|---|---|
| Memory | Ye won’t recall all o’ it in six months, nor do ye need to! |
| Collaboration | Others must be able to understand what ye’ve done without askin’ ye |
| Troubleshooting | When somethin’ be amiss, knowin’ what be normal be priceless |
| Reconstruction | If a server be sinkin’, ye need to know exactly how it were rigged up |
| Auditability | What were changed, when, and by whom? |
Write the documentation for “future ye”
The best rule o’ thumb: write as if ye be explainin’ it to yerself in six months time. That way ye be sure to include enough detail without overcomplicatin’ things.
Types o’ Documentation in IT Operations
Network Charts
A network chart shows the physical and/or logical structure o’ the network. ‘Tis can be anythin’ from a simple sketch to a detailed diagram with VLANs, IP addresses, an’ firewall rules.
A good network chart should contain:
- All network devices (switches, routers, firewalls, access points)
- VLAN structure with subnet
- IP addresses for important devices (servers, gateway)
- Connections between devices
The IP Chart o’ Treasure
An IP chart be an overview o’ how the IP addresses be scattered across the network. It helps ye keep order and avoid clashes (two vessels with the same mark).
Example:
| VLAN | Name | Subnet | Gateway | DHCP-range | Notes |
|---|---|---|---|---|---|
| 10 | Administration | 10.0.10.0/24 | 10.0.10.1 | .100 - .200 | Restricted access |
| 20 | Crew | 10.0.20.0/24 | 10.0.20.1 | .100 - .250 | |
| 30 | Scallywags | 10.0.30.0/24 | 10.0.30.1 | .100 - .250 | Internet only |
| 50 | Ships | 10.0.50.0/24 | 10.0.50.1 | None (static) | Fixed IP addresses |
Static marks:
| IP-address | Vessel | 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 be ensurin’ nothin’ be forgotten, aye. They be especially useful for tasks ye do less often, like settin’ up a new server or carryin’ out a security review.
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 be workin’
Changelog
Each time ye make a change to a production environment (server, network, service), ye should be documentin’ it. A simple log will do, aye:
## Change Log
### 2026-04-14 - Upgraded Nginx
- **What:** Updated Nginx from 1.24 to 1.26
- **Why:** Security patch (CVE-2025-XXXX)
- **Who:** Ola
- **Result:** Aye, no downtime
### 2026-04-10 - New VLAN for IoT
- **What:** Created VLAN 40 for IoT booty
- **Why:** Isolate IoT from the rest o' the crew's network
- **Who:** Kari
- **Result:** Aye, all printers moved to VLAN 40
Use Git!
If ye be writin’ the documentation in Markdown files (highly recommended), ye can keep ‘em under version control with Git. That way, ye’ll have an automatic log o’ all the changes, and ye can spy who changed what and when!
Ship’s Log
Ship’s Log describes how a system be workin’ in its current state:
| What | Example |
|---|---|
| System Architecture | “We be runnin’ Proxmox with 3 VMs: web, db, monitorin’” |
| Access Info | “SSH via port 22, only from VPN” |
| Backup Routines | “Daily backup at 02:00 to external disk” |
| Contact Information | “If trouble arises, contact Ola (admin)” |
| Recovery Steps | “Restart with: sudo systemctl restart nginx“ |
Tools for the Logbook
| Tool | What it be used for | Perks of the Bounty |
|---|---|---|
| Markdown | Text with simple markings | Light, portable, works with Git |
| draw.io | Diagrams and maps of the seas | Free, visual, exports to a picture |
| Obsidian | Note-keep with Markdown and links | Good for yer own treasure trove |
| MkDocs | Publish Markdown like a web page | Professional documentation |
| Git/GitHub | Version control for yer scrolls | History, crewwork, backup |
Task 1 - Chart a Simple Network
Use draw.io (free as the sea) to chart yer network at home or school:
- Begin with the internet connection and the router, aye.
- Add switches and access points, savvy?
- Chart in servers, PCs, and other devices.
- Write down IP addresses where ye know ‘em.
It need not be perfect, matey. The point be to start thinkin’ visually about the network.
Task 2 - Craft Yer Own Checklist
Think on somethin’ ye do regular with IT (like settin’ up a new VM, installin’ a development machine, or configurin’ VS Code). Write a checklist for the process:
- What be all the steps, aye?
- What do ye most often forget, savvy?
- Can ye simplify any steps, me hearty?
Save it in a Markdown document so ye can use it next time.
Task 3 - Document One o’ Yer Services
Choose a service ye’ve set up (a VM, a Docker container, a web server) an’ write a short operational documentation:
- What does the service do, aye?
- How do ye start/stop it?
- What be the IP address an’ port?
- Be there any backups, savvy?
Write it in Markdown an’ put it in a Git repository.
Summary
- Charts for yer future self: Write as if explainin’ to a landlubber who knows nothin’
- Network maps and IP plans give ye an overview o’ the infrastructure
- Checklists ensure nothin’ be forgotten when repeatin’ tasks
- Change logs track what was done, when, and by whom
- Operational documentation describes how the systems be workin’ today
- Use Markdown + Git for simple, version-controlled documentation