为什么你写的文档没人看
上周同事小李折腾了三天才搞定一台交换机的端口镜像配置，后来才发现老张去年就处理过一模一样的问题，还写了文档——藏在某个共享文件夹的“临时资料”里，文件名是“新建文本文档(2).doc”。这种事在办公室太常见了。写文档不是为了应付检查，而是避免重复踩坑。你花两小时写的清晰步骤，可能帮团队省下几十个小时。
从“能用”到“好用”的三个细节
运维文档最怕写成命令流水账。比如只写“执行ipconfig /all”，却不说明这个操作是为了排查DHCP获取异常。读者得自己猜上下文。正确的做法是先交代场景：“当用户报修无法上网时，登录终端执行以下命令查看IP配置状态”。
时间信息也很关键。某次我按文档升级防火墙固件，结果发现步骤里的下载链接已失效。翻看文档属性才发现这是四年前的版本。现在我会在每篇文档开头加一行：
版本：v1.3
更新日期：2024-03-15
适用设备型号：FortiGate-60E及后续版本
截图比文字更直白
配置SNMP监控时，文字描述“在管理界面找到告警阈值设置项”容易让人迷路。直接贴一张带红色方框标注的界面截图，旁边用箭头指向“Threshold Configuration”区域，效率提升不止一倍。手机拍屏幕也行，但记得先调亮显示亮度，避免反光糊成一片。
代码块要能直接复制
提供可复用的脚本时，把完整命令封装好。比如批量修改Linux主机名的场景：
#!/bin/bash
# 批量更新主机名脚本
# 使用方法：./update_hostname.sh new-host-01
if [ -z "$1" ]; then
echo "请指定新主机名"
exit 1
fi
hostnamectl set-hostname "$1"
echo "127.0.0.1 $1" >> /etc/hosts
systemctl restart rsyslog连注释和使用说明都包含进去，别人拿过去改个名字就能跑。
留个“后门”给未来自己
所有文档末尾加一个“变更记录”表格。上个月我接手一台奇怪行为的服务器，查到最后发现是前任管理员临时调整过内核参数，但没留痕迹。现在我的文档都会包含：
2024-02-20 张伟 初始版本
2024-03-08 李娜 增加SSL证书更新流程
2024-03-22 王涛 补充防火墙策略放行规则谁改过哪里一目了然。顺便提醒自己：别在周五下班前写重要文档，脑子发懵时漏掉的关键步骤，够你下周debug两天。