为什么要写好文档

关于写产品文档这件事，很多人都觉得说写文档能力不是那么的重要，能将想法清楚的告诉研发，并保证执行效果，就可以了，文档只是辅助的一个东西。

对于这个观点我不是很认同，我认为能写出好的产品文档不一定是一个好的产品经理，但是连一个文档都写不好的产品经理，一定不是一个优秀的产品经理，文档不仅是要给开发看，更多的作用是帮助你梳理逻辑关系，检查逻辑的严谨性，提前暴露出潜在的问题，如果这个环节被简单的略过，后面一旦因为逻辑的不严谨而导致返工，对于整个项目的效率简直是致命的。

写文档容易陷入的误区

我自己刚开始做产品狗的时候，天天被吐槽产品文档写的烂，逻辑看不懂，被研发说了之后，下定决心要把文档写的事无巨细，每个潜在的逻辑都罗列到文档里，列的越来越多后，产品文档的幅度也不知不觉的越来越长，以至于后面连我自己都没有耐心看长达6、7页的文档，于是我看了很多其它优秀产品经理写的文档，搜索了很多如何写产品文档的建议和说明，发现了一个规律，好的产品文档一定是精简且能抓住重点的，当然，这个只限于在移动互联网以敏捷迭代方式开发的团队，一般传统互联网项目类型的公司，还是需要产品经理写出“事无巨细”的产品需求说明“书”。

在我看来，写产品文档应该是有过程的，不是一步到位，是根据自己的思考，以及需求评审会上大家的意见，不断修改出来的，所以可以说产品文档是“改”出来的，而不是“写”出来的，刚开始我一上来就会陷入这种误区，在需求评审之前，将文档写的尽可能完善，开完会后需求将文档底朝天的修改一遍，然后再评审，再修改，再评审，再修改......每一次修改就相当于是重新写了一份文档，在文档上投入的时间太长，效率太低，后来我认真思考了一下这个问题，逐渐觉得写文档是需要有“节奏”的。

写文档的节奏

1、在需求想法的初期，文档不需要写的很详细，只需要一个草稿就好，因为这个时候除了你自己之外也没有人看，只需要将自己整理出的思路提炼出关键点写在文档上，这个时候文档的作用更多是帮自己梳理逻辑，所以不需要投入很多时间。

2、在需求想法的中期，找到所有的同事进行讨论交流，听听大家的意见，优化你的方案，这个时候你的脑子中应该已经有比较明确的想法，将草稿整理为比较成型的文档，这个时候不用过于补充细节方面的东西。

3、在想法比较成熟的后期，进行需求评审前1小时，群发你的文档给对应相关的同事，并确保邀请到了有决定权的人参加评审。

4、需求评审阶段，这个时候大家更应该讨论关注的具体怎么做的细节，而不是为什么这么做和做什么，因为在需求想法的中期，尽可能多的跟大家沟通已经确保了利益相关方对你想法的支持，然后根据评审结果不断修改补充文档，然后再发给大家，再进行评审，直至团队里的人都认为这个方案没有问题。

5、评审后阶段，一般需求评审后紧接着就要准备设计和开发了，所以在评审后的阶段中，你需要将最终确定的方案所有细节补充完整，确保无遗漏，设计和研发及测试团队，可以直接根据你的文档开始工作。

产品文档包含的内容

1、所要解决的问题是什么，确保大家在对目标理解一致无歧义，这个是后面大家讨论的基础，很重要。

2、需求的背景是什么，要解决这个问题，我们需要在哪些方向上去尝试，哪些我们做的比较好，哪些我们还要花比较大的力气去尝试，尝试的方向是什么

3、可衡量的目标，明确承诺交付和成果，明确哪些事情超出了此项目的范畴，如果目标是可衡量的，则确定对应的数据指标，如果所做的事情比较创新，不太容易找得到量化的成果，那也应该向大家解决了什么问题即算成果达到

4、具体解决的方案，如果是移动互联网的话，就会分为客户端逻辑和后端逻辑，一般来说后端逻辑比较难以当面阐述，需要以文档形式表示

5、相关同事各自任务的情况，比如我们是以 Jira 形式管理任务的，任务明确后建立 Jira 后，我会贴在文档里，后续也好找当时对应的负责人

6、时间点确定，什么阶段完成至什么样的程度，什么时间截止开发，这个一般来说多当面沟通，就不会有时间不明确的情况

写产品文档的技巧

1、控制篇幅尽量简短，不要写长篇大论，能精简尽量精简

2、多使用图表，比如产品的状态变更，用表格的形式体现很清晰，比如后端的复杂逻辑，用流程图表达会很清晰

3、语言不要过于花俏，让人能快速理解你的想法最重要

4、像工程师一样思考，你的文档大多数都是给工程师看的，所以尽量考虑到他们的感受，以他们的视角去考虑如果写文档，比如涉及到客户端的一些东西，写清楚错误处理应该怎么做，断网情况下显示什么

5、高保真原型及交互图，最好能有，但是不是必要，高保真能减少很多理解上的误区

6、产品文档历史变更记录，第一版本是什么时候写的，第二个版本是什么时候写的，变更了哪些内容，之后大家再看文档的话，只需要在意那些变更的内容就好了，不需要重头再看一遍哪些地方改了

另外，贴另外一篇关于写出高质量产品文档的帖子，我觉得写的蛮不错的，另外一篇是中文翻译

https://goberoi.com/on-writing-product-specs-5ca697b992fd

https://zhuanlan.zhihu.com/p/23778590