ARTICLE · 1100613
会写代码的人很多, 会写文档的人最值钱
〇、先看全局：三类文档，各管一段
判断方法很简单：先问"这份文档写给谁看"——读者不同，写法完全不同。
一、操作说明：写给第一次用的人
判断标准就一句话：不用问、照着做、不出错。做到了，用户不来烦你；做不到，你就是永久的人工客服。
它解决什么？
它的核心：只讲"怎么做"，不讲"为什么"
用户此刻只关心下一步点哪。设计原理、背景逻辑统统不要写在这里——那是产品说明的事。
写好必须有的 5 个黄金要素
1入口在哪：从哪里进、路径写死。例：系统 → 数据管理 → 导入。
2前置条件：权限、账号、文件格式、网络、配置，先说清楚再开做。
3步骤动作：一步一句，动词开头——点击、输入、选择、上传。
4预期结果：每一步出现什么才算对（"此时应弹出绿色提示'导入成功'"）。
5异常处理：报错怎么办、卡住怎么办、失败怎么回退。
怎么写最吸引人、最有用
· 截图比文字强 10 倍：关键步骤配图，红框圈出按钮位置。· 步骤不要跳：你觉得简单的地方，恰恰就是别人找不到的地方。· 语言越通俗越好：别堆术语，用户不是工程师。· 重点标红：易错点、必选项、禁操作，一眼可见。
二、产品说明：写给所有人，统一认知
它的读者最杂：产品、开发、测试、客户都要看。所以它的唯一使命是让大家理解一致——消灭"我以为、你觉得"。
它解决什么？
它的核心：讲清"是什么、有什么、规则是什么"
它不教操作、不讲实现，它定义"这个产品到底是什么、边界在哪"。争议来了，翻它。
写好必须有的 5 个关键内容
1业务目标：这个功能解决什么问题、为谁解决。
2功能清单：模块、页面、按钮、能力，一一列全。
3业务流程：主线流程、异常流程、状态流转（一张流程图胜千言）。
4规则约束：必填、校验、权限、限制——写死，不留模糊。
5输入输出：数据从哪来、处理逻辑是什么、结果长什么样。
怎么写最清晰、最让人信服
· 先用流程图，再用文字：人对图的理解远快于段落。· 先讲整体，再讲细节：先给全景，再逐模块展开。· 规则写死，不模糊、不含糊："大概""基本""视情况"是扯皮之源。· 一定要写"不支持的功能"：这一节最不起眼，却最能避免扯皮。
三、底层代码说明：写给接手的人
代码是写给人的，不是写给机器的。半年后的你自己，就是第一个"接手的人"。这份文档决定：系统是可维护、可迭代，还是死在你手里。
它解决什么？
它的核心：讲清"结构、逻辑、设计思路"
它不是注释的堆砌，而是回答一个更难的问题：为什么这么设计、代价是什么、边界在哪。
写好必须有的 5 个硬核要素
1架构总览：分层、模块、依赖关系（先给图，再给文字）。
2核心数据结构：表、实体、关键字段及其含义。
3主流程逻辑：入口 → 处理 → 输出，一条线讲通。
4关键算法 / 规则：复杂逻辑、判断条件、计算公式（例：条码总数 = 订单套数 × 每套包数）。
5坑点与注意：已知问题、禁忌操作、待优化点——这部分最值钱。
怎么写最专业、最省心
· 先画架构图，再写文字：让人 3 分钟建立全局感。· 讲"为什么这么写"，不只讲"做了什么"：设计取舍才是交接的核心资产。· 边界、异常、并发一定要写：这三个地方出事最多、最难查。· 保持更新：代码一变、文档同步——过期的文档比没有更危险。
四、三类文档对照表（收藏这张就够了）
| 维度 | ① 操作说明 | ② 产品说明 | ③ 代码说明 |
|---|---|---|---|
五、为什么你必须写好这三类文档？
操作说明写得好：用户不烦你产品说明写得好：团队不吵你代码说明写得好：后人感谢你
六、行动清单：从今天这份文档开始
✅ 可直接照做的写法
· 动笔前先回答三个问题：写给谁看？他要完成什么？他会在哪里卡住？· 操作说明：每一步都配"预期结果"，报错场景一个不落。· 产品说明：专门开一节写"不支持的功能"，规则能写死就写死。· 代码说明：先画架构图，再写"坑点清单"，交接时一起给。· 给自己定一条铁律：代码合入、文档同步；不改文档的改动，等于没做完。