上周帮隔壁公司处理一次交换机批量掉线，翻他们内部的《网络维护手册》翻了二十分钟没找到SNMP轮询超时的默认值——最后发现那页PDF压根没更新，还写着十年前的老型号。这事让我意识到：不是没手册，而是手册写得没法用。
别把手册写成说明书
很多团队一上来就抄设备厂商PDF，堆砌参数、术语、命令行全集。结果呢？新人对着‘配置VLAN Trunk端口’卡住，因为手册里没写‘插错网线会导致Trunk协商失败’这种真实场景。手册不是教科书，是给正在凌晨三点排查丢包的人看的救命纸。
先列这三类问题，再填内容
打开空白文档前，先问自己：
• 哪些故障每周至少发生1次？（比如DHCP地址池耗尽、防火墙策略误删）
• 哪些操作新手最容易手抖？（比如reload核心交换机前忘了保存配置）
• 哪些信息查起来最费时间？（比如某台AP的管理IP藏在机房贴纸背面）
把这些塞进手册，比罗列所有命令有用十倍。
结构越简单越好
我们团队现在用四块拼图：
速查页：一页A4，印着常用密码、核心设备IP、紧急联系人、重启服务命令（
systemctl restart networking排障流程图：‘用户报无法上网’→查物理链路→查DHCP分配→查DNS解析→抓包定位；
配置模板：不是命令大全，是‘给新接入层交换机配管理VLAN’的完整步骤+注释；
变更记录表：每次改策略、升级固件都手写日期、操作人、影响范围，不许留空。
拒绝静态文档
我们把手册放在GitLab里，每次修改都提MR，老员工必须review。上个月有人把‘备份配置脚本路径’从/opt/netbak/改成/srv/net-backup/，改完立刻触发邮件通知全员。没人再问‘最新版在哪’——最新就是master分支。
一个小技巧
每份手册开头加一行：上次更新：2024-06-12（张工，修复了AC控制器证书过期检查步骤）。日期和人名写死，逼自己保持更新。
手册不是交差材料，是你下次被电话叫醒时，能30秒内翻到答案的东西。