前几天帮公司新来的实习生搭内网穿透，本以为几分钟搞定的事，结果折腾了快两个小时。问题出在哪？不是网络不通，也不是工具有 bug，而是官方给的那篇帮助文档——看得人一头雾水。
“按以下步骤操作”到底哪几步？
打开文档第一眼就是一句：“请确保已正确配置本地服务，并按以下步骤操作。” 然后下面列了五个带编号的条目，可前三条讲的是客户端启动命令，第四条突然跳到“检查防火墙策略”，第五条又说“确认 tunnel ID 已注册”。顺序乱得像拼凑出来的，根本不知道该从哪开始。
最离谱的是，关键参数如 --token 和 --subdomain 根本没说明白什么时候要填、怎么生成。实习生照着抄了一通，结果连不上还死活不知道错在哪。
错误提示比谜语还难猜
运行命令后报错：ERR_TUNNEL_CONN_FAILED。翻遍文档，在“常见问题”里找到一行字：“可能是目标地址不可达。” 这等于没说。到底是本地服务没开？还是端口被占？还是服务器那边挂了？文档一个排查路径都没给。
后来我自己试出来，原来是 config.yml 里 protocol 写成了 http，实际要用 tcp。但这点在文档里藏在“高级配置”子页面的第三段小字里，压根没人会注意。
真实场景需要的是流程，不是术语堆砌
很多开发者写帮助文档时，习惯把 API 参数表甩出来就完事。但用户真正需要的是：从零开始，一步步带你走到成功连通。
比如我要用 frp 暴露本地的 Web 服务，文档应该告诉我：
- 先确认本机 80 端口有没有服务跑着（可以用 curl 测试）
- 编辑 frpc.ini，填好 server_addr、server_port、local_port
- 加上 type = http，如果想自定义域名再加 subdomain
- 启动客户端，看日志有没有 “start proxy success”
代码示例不能只给一半
有些文档倒是放了代码块，但变量全用 placeholder，比如：
frpc -c <config_path>新手根本不知道 <config_path> 到底写 ./frpc.ini 还是 /etc/frp/frpc.ini。正确的做法是直接给个完整例子：
frpc -c ./frpc.ini别让用户自己拼图
我见过最气人的文档，把安装、配置、启动、调试拆成四个页面，每个页面只有三句话。你想完整搭一遍？得来回点四次，还得自己记住上下文。
好的文档应该像做菜教程：备料、切菜、开火、调味，一气呵成。哪怕多写几百字，也比让用户摸黑强。
现在我们公司内部已经重新整理了一套内网穿透操作指南，谁来都能十分钟上手。说到底，技术文档不是写给机器看的，是给人用的。连这点都忘了，再牛的工具也发挥不出价值。