产品文档撰写指南：被你忽视的这些流程

产品文档撰写指南

很多人听到「产品文档」这四个字就像吞了苍蝇一样，人们常日会认为这意味着又要花几周写一个根本没人看的文档。
如果一个团队总被产品文档这种事情拖累，怎么可能「敏捷」得起来，怎么可能高效地产出代码？

我在过去十几年创造了多个数百万人利用的软件产品之后，加倍认为这种不雅观点是完备缺点的。
根据我的履历：

高效的产品文档是创造伟大产品的过程中所不可或缺的主要组成部分。
撰写产品文档可以逼迫所有人从项目初始就理性思考，频繁沟通，明确权责——所有的这些都会带来更好的软件质量，更低的进度风险，以及更少的韶光摧残浪费蹂躏。

在这篇文章中，我会通过一个案例来分享一些普适的建议，这些建议会对大中型（超过二百人的）公司中的产品经理们非常有帮助。

首先，举个例子

假设你在这里事情：

一家从事在线旅游预订做事 （就像 Hotels 或者 Airbnb 但是规模更小一些）的公司。
目前这家公司的支付转化率偏低，以是这个季度大家打算考试测验通过在支付环节加入在线客服的方案来提升转化。

你的工单/用户故事/路线图是：

通过在支付环节增加在线客服来考试测验提高支付转化率。
支付转化率目前仅有 18％，而业内均匀转化率有 30％。
我们打算测试下在支付时展示在线客服谈天窗口是否可以提高这个转化率。
用户运营团队已经赞许了供应 1 人月的客服人力支持。

在你没有产品文档时，你会这样做：

比方说，你以为行动起来总是最主要的，因此直接开始动手：

在迭代操持会上，你和团队谈论了这个需求。
然后你挑选了一个靠谱的第三方客服供应商（例如 SnapEngage）。
提交一个工单来让工程师添加一些 Javascript 代码。
和支持团队开个会，确定他们都准备好了

搞定了！
这么大略的事情怎么能要我们写产品文档呢？如果你是在一个小型创业团队，你也确实并不须要——由于产品改动相对小，涉及到的人也相对更少。

但如果你是在一个更大的组织之中，或者产品更加成熟/繁芜，就会陆续涌现下列这些问题，并且比较写文档，这些问题会须要更多韶光来处理。

例如：

工程师把工单标记完成了，但是一验收测试，就创造这个功能完备没有考虑移动真个适配。
「唉呀！
你忘了提醒大家手机真个利用才是核心场景。
」用户运营经理打算开展一个漫长的评审流程，以确定最得当的谈天做事商。
「啊……须要定一个会议，向大家阐明下这次上线只是一个灰度测试。
」发布一小时后，客服报告说他们收到了西班牙语的在线谈天要求。
「啥？要追加一个紧急发布，把这个测试限定在英语用户中。
」一个设计师花了几天，为谈天窗口滑入屏幕的交互绘制了一个完美的动画。
「用户体验过度优化，你是否对全体团队统一了「这次只是一个测试」的预期？」一周的测试完成之后，数据剖析师创造无法产出你要的报告，由于干系的必要指标并没有埋点。
「史诗级的失落败。
从头再来吧。
」

如果这是一个相对大略的项目，纵然没有产品文档可能也不至于陷入这样的灾害之中。
但是在大略的项目中你仍旧有可能会由于没有文档摧残浪费蹂躏许多韶光和机会本钱。

如果你写了一篇文档

为了便于解释，我准备了两个示例文档：一篇思路条记，和一篇完全的产品文档示例——这样可以完全先容产品文档的撰写流程。

请在连续阅读文章之前，花几分钟读一下这两篇示例文档吧。

这是一个根据你已知的信息和想要解答的问题所梳理成的列表。

这会是你须要做的第一件事情，大约须要一个小时来完成这个文档。
这个文档会成为你和团队中其他人的一个沟通根本。

只有和团队一起评审了你的假设和创意之后（无论是在专门调集的会议上，喝咖啡时，或者桌上足球的安歇韶光），你才该当真正开始写产品文档。

如果已经完成了沟通和评审，全体文档该当花费你 1-3 个小时的韶光。

啊哈！
有了文档之后是不是就觉得踏实多了？写文档看起来是额外的事情本钱，但是实在并不是，高效的文档可以帮助你和你的团队节约韶光投入，并且在交付上线时会更有信心。

等等！
——你已经读完示例文档了么？请务必先读完它再连续阅读下面的文章。

Ben Horowitz

文档撰写指南

我通过示例文档诠释了这篇文章中所讲述的思考，在连续阅读全文之前，请务必确认你已经阅读了示例文档 。

为什么要写产品文档？

为了以更高的质量、更快的速率和更佳的预判来交付精确的产品。

是的，便是这样。
那么，产品文档将如何帮助你做到这统统呢？Ben Horowitz 分享了上图中这个意见，我的示例文档也是一个很好的例证。
明确一下要点：

从一开始就理性思考：在团队开始付出更高本钱去设计软件架构、履行代码开拓、完善界面设计、测试软件质量之前，写文档可以迫使你提前思考每一个细节。
这将会提高你决策的质量，降落意外事宜发生的概率。
高效沟通：你常常须要和不同的利益干系方（支持团队，工程团队，设计团队，财务团队，管理层等等）沟通你的方案。
产品文档可以帮助你事半功倍地完成沟通，避免口头沟通中产生的歧义，团队中的所有人可以更好地理解你的意图，并且更对症下药地做出答复。
明确权责：明确项目目标的评价标准，公开承诺赏罚勉励机制：利益干系方可以知晓如果末了一刻变更需求会意味着什么，工程师们也会在预估工期时再三推敲。

产品文档中应该包含哪些内容？

产品文档该当明确沟通要做一个「什么」产品，以及「为什么」要这么做。
用来解释清楚一个产品的表达办法很多，但最核心的，一定要说清楚这五件事情：

问题：描述你这次打算办理的问题。
更主要的是，阐明为什么要去办理这个问题。
描述要尽可能地详细，并且供应干系的数据指标。
可衡量的目标：明确承诺交付和成果，明确哪些事情超出了此项目的范畴。
每一个目标，都该当可以明确衡量「是否达到目标」。
需求背景：供应你的不雅观众理解当前问题以及接管你的发起所需的所有背景信息。
包括但不限于假设、用例、数据指标等信息。
办理方案详情：你的发起该当有充足的细节，易于团队成员消化理解及实行——可以把这部分内容想象成对人脑进行编程和实行。
韶光轴：列出你的团队共同认可的截止日期和其他主要韶光点。
这部分内容开始的时候可能会比较模糊，但是在末了一次文档评审之前应该完备敲定。

你可以利用我的示例文档做你的文档模板，按照你的想法增/删/改任何章节。
只要你能够清晰并且条理清楚地表述上面提到的这五点信息，文档形式并不主要。

如何写产品文档？

接下来我会先容我撰写和评审文档的常规流程。
根据项目大小，利益干系方的数量不同等情形，流程细节可能会有所变革，但是大体的流程是确定的。

（1）快速完成一个草稿（1-2 个小时）

关闭电子邮件和谈天工具。
泡杯茶，坐在椅子上开始思考，然后逐一把你所理解的信息列成清单（见上文中的思路条记示例）。

（2）安排几个 30 分钟的一对一会议 （1-4 个小时）

这个步骤的目的是过一遍文档中的细节，优化你的方案，并且得到更多人的支持。
尽可能掌握这些会议的规模，人越少越好（空想状态下都该当是一对一会议）。

在本文的示例中，我会和客服部门的卖力人，一个财务职员和一个工程师分别安排一次会议。

（3）撰写和编辑文档 （0.5-3 天）

此时，你该当对能做，并且该当做什么有了一个明确的想法，但是大脑中塞满了大量的细节等待着梳理清楚。
于是接下来须要将所有这些细节都整理出来，并且逐一梳理推敲。

在完成初版文档之后，须要连续大篇幅编辑修正，常日终极的文档可以在你的初版草稿的根本上压缩 30%-50% 的长度，简洁和清晰的文档就意味着更加随意马虎阅读。

大部分文档都可以在半天到一天的韶光里完成，不过实际上也会有一些文档须要两三天才能写完。

（4）群发文档并且安排一个 1 小时的评审会议（15 分钟）

将文档群发给项目的所有利益干系方，并且抄送给其他可能对文档感兴趣的团队（例如你所在的产品团队，全体支持团队等）。

跟进这些关键职员是否接管了会议约请：将会实行这件事情的人，和所有对这件事情有通过/反对权力的人。

（5）评审文档（1小时）

在开始会议之前，讯问是否有参会者没有详细阅读你的文档。
常日都会有一两个人中枪，在这种情形下可以说：「没问题，我们先用 10 分钟一起来看一下文档。
已经读过文档的人可以利用这个韶光先放松安歇一下」。

这次会议上你须要得到利益干系方的赞许，并且得到实行方（工程师、支持团队等）的知晓、认可以及人力支持。

你可能须要开多次评审会议，并且根据评审会议上沟通的信息不断修正文档。

（6）通过评审后，及时同步信息和建立工单 （1-2 小时）

会后同步信息的电子邮件须要包含更新后的产品文档链接，和此项目干系的工单链接（例如「在页面上添加 JavaScript 代码」，「完成数据剖析报告」，「测试 Staging 环境」，「和支持团队预演流程」，等等）。

一样平常接下来将会有一位工程师完成技能文档，不过并不总是这样（文中的示例项目就不须要这一步）。

写出高效产品文档的进阶技巧

只管即便简短

没有比这更主要的文档写作建议了。
简洁意味着清晰的思路和沟通，也意味着你的文档更加易于阅读和理解——这一点至关主要。

利用平白的措辞和大略的格式

利用简短而不是花哨的语句，利用列表和加粗强调可以使文章更一览无余，以放松有趣的办法写作而不是一板一眼，如果你有得体的诙谐感就再好不过了。

为开拓团队预留韶光

通过评审并且达成同等通过的文档才是完善的文档。
如果你希望在未来的某一个迭代 Sprint 中开拓此项目，就该当提前两到三周开始这个产品文档写作流程。

像工程师一样思考

在项目得以进入开拓之时，常常会创造大量未预见到的边缘情形——但这种环境实在可以避免。
如果你负责考虑过项目进入开拓的所有必要条件，你就可以提前创造这些问题（例如，是否在移动设备中可以利用在线谈天功能？）。

确保每一个人都跟上了你的节奏

当我组织产品评审时，会议室里的大部分人都已经大致理解我要讲的内容——由于我已经提前在谈论会和日常谈天中沟通过这个事情了。
既然大家都已经清楚了「做什么」和「为什么要做」的问题，文档评审会上我们只要关注履行细节就好了。

在图表中下功夫

流程图、线框图等图表可以通过易于理解的办法供应很大的信息量，同时也须要花费非常多的韶光来制作这些图表。

在思考和写文档上花 0.5-3 天韶光

详细韶光根据项目大小而定。
花费在写文档上的韶光越长，所带来的边际收益就会递减。
特殊须要指出的是，没有人能够读的下去超过 5-6 页的文档。

指明方向，明晰愿景

你不仅仅是在定义一个功能，也是在阐明「为什么我们要做这件事情」以及「我们的目标是什么」，在文档中指出这个项目将会对更高层面的方案造成什么影响，以及接下来会发生什么。

确保你的不雅观众阅读了文档

如果你的文档又臭又长，或者从来不分享给对应的人，那你还不如不写文档。
务必确保你的文档被对应的人阅读了，我上面关于评审开始时留韶光给大家读文档的建议值得大家参考。

获取诚挚的反馈

你的文档是否是在赘述人尽皆知的事情？或者是文档缺少足够的细节？是否在后续履行中创造了太多的边缘情形？又或者，是否在制订操持和文档评审上耗费了太多的韶光？你该当和你的团队时候保持沟通。

说好的敏捷开拓（Agile/Scrum）呢？

我知道会有争议，但是产品文档和敏捷宣言的原则没有丝毫冲突，并且在类似于 Scrum 这样的敏捷方法上得到了充分发挥。

毕竟，用户故事（Story）许多时候须要详尽的描述，文档可以增加沟通中的清晰度和可传播性，为什么非要刻板地认为仅仅利用口头沟通和利用白板才算是敏捷开拓呢？

「产品文档会导致发布变慢，过度方案，常日会摧残浪费蹂躏韶光」的想法完备是无稽之谈。

我事情过的多个天下级团队遵照着一些敏捷原则（例如两周一个迭代周期），每天（乃至更频繁地）发布代码，并且以发布产品（而不是文档或者会议）作为衡量成功的标准——这些团队也都仍旧认为文档是他们打造成功软件的一个关键部分。

你对技能文档怎么看？

我是一个技能文档的支持者。
产品文档常日关注 做什么 ，而技能文档更多关注在如何做 。
这两种文档为研发流程中的不同环节带来同样的清晰视角，并且都使得工程师（和他们的用户）身心愉悦。
未来如果大家有兴趣的话我可能会写一篇关于技能文档的文章。

总结

感谢你读到这里。
如果你认为这篇文章有用，请分享给其他人——特殊是你的产品/工程团队。

如果你想看更多的产品经理内容（例如：方案产品路线图），或者想理解其他人如何利用产品文档， 请用两分钟填写这个小调查（英文）。
我会在未来的文章等分享调查结果中故意思的信息。

以上，祝写文档愉快！

备注感谢周思博（Joel Spolsky） （微软早期 PM，曾参与创办 Stack Overflow，Trello，FogBugz 等产品，《软件随想录》作者）的「文档是对人脑的编程」的比喻。
早在2000年，他写了4 篇关于文档的系列文章（英文），这对我的 PM 道路产生了巨大的影响，强烈推举。
在顶部的引文中，贝索斯所说的条记是指为高层管理会议利用的，先容新业务/产品创意的备忘录。
这实际上不算是产品文档，但是两者并不是完备不一样。
贝索斯在会议开始的时候会组织所有人默读文件——这引发了我在文档评审时做同样的事情。
来源感谢 iDoneThis 博客这篇关于写作的代价的文章（英文）。
这是贝索斯和 Horowitz 的弁言的来源。
感谢 Vikram Oberoi 。

原文作者：Gaurav Oberoi是 SurveyMonkey 的（前）联合创始人，曾于 Amazon、Xmarks 先后从事工程师、产品经理等职位，在西雅图和硅谷有十余年的事情履历。

原文地址：https://goberoi.com/on-writing-product-specs-5ca697b992fd

翻译：Tomy

译文地址：http://zhuanlan.zhihu.com/p/23778590

本文由 @Tomy 授权发布于大家都是产品经理，未经作者容许，禁止转载。