如何写一篇产品文档

开篇

笔者有着多年的toC开发、运维开发和运维工作经验，也曾开发很多内部运营系统，更多是从功能角度出发满足业务运维的需求很少提供完整规范的产品文档，关于开发的运营系统使用方法更多是通过口口相传，听起来不是很正规但确实是这样走过来的。

笔者也反观公司内部的运营系统也会出现笔者遇到的情况，或者是提供了基本的文档但随着时间的推移文档年久失修，甚至出现问题联系文档里的负责人已经离职的囧境。

两年前笔者开始从事toB业务明显感觉到与toC业务的不同，相应的产品要有配套的文档和说明书且产品文档要优先于版本迭代，最起码也需要同步于产品迭代功能发出。

ToB面向企业级别用户文档是一个必不可缺的产物，但用心整理的产品文档并提供用户也会遇到一些问题，譬如产品运营的过程中我们经常与用户交集的Helper(在线服务客服)会比较困扰因为用户没有看文档的习惯更喜欢直接来问Helper，所以有时也在思考是否要投入更多的经历来完善文档？ 为什么用户不看文档？我们的产品是否出现了什么问题？很多的问号盘旋在脑海中。但思考过后最终的答案还是非常肯定的文档是产品非常重要的一个环节，用户可以不看但我们一定要提供并且精心的维护它。下面就通过一个真实的案例ULS产品文档开发过程，来介绍如何写一篇产品文档，以下是ULS产品文档目录结构。

ULS产品背景介绍

ULS(Unified Log System) 统一日志服务，是内部的一套开发上报日志、存储和最终消费一站式平台。 此产品是在2018年底开始由我们部门负责，从ULS代码注释中可以看到它大概7年前（2012）开发的是一个有历史的内部日志系统同时有一批忠实的用户。

竞品文档结构调研

ULS产品是一款有历史的内部系统经过了多年的发展，文档散落在各处另外很多文档也年久失修有很多的错误，我们优先整理了旧文档列表并验证旧文档没有问题后，统一放到现有系统显眼位置让用户第一时间可以看到。接着我们对日志服务竞品的文档结构做了一些调研，这些产品包括腾讯云、A云和QN云，竞品目录结构对比可以访问（ https://docs.qq.com/sheet/DTkZRSGZORkZvdHZq?opendocxfrom=admin&preview_token=&coord=K15A0A0&tab=BB08J2 ）。

经过竞品调研并结合我们当前的实际情况,最终我们的文档结构一级目录为，版本更新历史、快速上手、5分钟视频介绍、产品介绍和FAQ问题整理等。 有了文档结构后在此基础上我们将老的文档中一些信息进行整理并灌入新文档系统中，这里强调一下我们使用的是GitBook来管理我们文档，有很多内部系统依然使用Word文档来管理，笔者觉得更加推荐GitBook它有版本管理功能，在并行开发文档过程中避免出现错误与覆盖的情况，同时可以对比不同版本间的差异方便我们优化文档，最主要他呈现给所有人是一个WEB网站，信息更新也更加的实时。

寻找用户群体

个人觉得做产品最重要一个环节是用户群体，只有了解用户群体我们在产品迭代过程中的取舍才会有依据。这里举个比较形象的列子也是笔者之前一直在思考的问题，为什么Windows系统有回收站而Linux系统没有回收站？后者的答案笔者在《Unix编程艺术》找到，这句话来自书的原文——Linux世袭了Unix的设计理念与传统，而Unix本身并没有这样的设计并延续到了Linux。Unix面向更加专业的用户 ,Unix的开发者喜欢清晰、简单的操作，用户告诉做什么就做什么，即便用户使用的命令等价于“向我开枪”的命令。而这样做Unix的开发本能辩解的就是：保护用户避免自我损害，应该是GUI或应用程序级别的事，而非操作系统。 所以可以很清楚的看Linux的用户群体更加的专业，Windows系统正好反过来，如果用相机比喻的话Windows更像傻瓜相机，Linux是一个专业的数码相机彼此之间有自己针对的用户群体。

我们对日志竞品产品调研也再次验证了这个结果，这里包括QN云智能日志平台 、A云日志服务和日志易等业界日志产品做了深入的调研并与ULS进行对比发现不同的产品在功能上是有取舍和针对性的(竞品调研报告：https://docs.qq.com/sheet/DTkdtREdPU2dES2ZG?preview_token=&coord=B4A0A0&tab=BB08J2)，从产品功能上来反推用户画像：

A云：用户群体需要具备更强的开发能力，而其系统更多像一个脚手架与A云产品相互打通，用户具备开发能力通过脚手架可以实现常用功能外的一些定制化开发需求。

QN云：用户人群需要有计算机的背景但并非一定需要较强开发能力，该产品提供了丰富的功能和强大的用户WEB界面，基本可以满足常见用户的80%需求场景。

某易：功能和文档十分不完整，从日志易的立足行业（金融、能源、运营商）看到，日志易有为不同行业提供不同的解决方案。用户画像：需要个性化定制日志服务的企业。

ULS(内部系统):目前内部运营了7年多有一定的铁杆粉丝量，所以ULS用户画像就是内部的开发，这些开发主要集中在CSIG、PCG和少量的IEG等，这也能看到我们系统用户的属性。

详细调研报告可以参考：（ https://docs.qq.com/sheet/DTlNZZE1FQ3hxc3NW?opendocxfrom=admin&preview_token=&coord=A4A0A0&tab=BB08J2 ）

有了用户群体后我们在写文档时就有了依据，譬如笔者在文档中写过ELK有同学会挑战需要介绍ELK是什么， 但我们的产品用户群体是开发，他们会具备一定的知识基础，依据这背景笔者是不会在文档中写过多的ELK介绍的。

文档正确性校对

在刚开始的时候我们从能收集到的历史文档中搬了很多东西到新创建的文档系统。这些文档多由老的日志系统开发撰写，在实际操作过程中我们发现安装文档执行并非100%执行成功或者说文档只写了在安装过程中最好的情况下是什么样的，我们通过多位测试同学不断的对文档验证与校对,并对文档中的内容进行重新排序与分类最终达到我们预期的效果。 这里有一个值得分享的案例，譬如我在安装日志服务的Agent，其实我们直接通过运营系统下发就可以了但我们运行的服务器环境在文档上并没有明确操作系统发行版本是什么，kernel版本号，是否经过初始化系统等。 笔者通过验证文档安装的服务器每次都会执行成功，而测试同学每次测试都失败，其实主要原因就是我们使用的服务器初始化系统不一样导致系统上缺少依赖包，测试同学在安装Agent时就会报错，这些细节都是通过一步步测试后发现并整理到文档中的。 而我们的文档在迭代过程中一定需要经过测试同学进行严格的流程测试才能保证它的正确性，最终提供给用户也是靠谱的手册。

一定要有的CHANGELOG

在产品开发过程中一定要通过版本来迭代需求。 以ULS为例，我们有自己的用户群体，在用户群里中又建立了产品相关的社区，通过社区的反馈不断收集用户的意见，根据用户的意见在每次版本迭代中进行优先优化，每一个版本我们都能看清楚他的优化点与用户关心的问题，每次迭代一个版本并对比版本之间的变化会发现你的产品会更上一个台阶，我想这也是做好一个产品的方法之一。

不能没有的FAQ

开篇我们说过其实最头痛的是提供了用户文档用户不去看，我想这也是很多人的用户习惯，如果文档与Helper都在的情况下，很多人会优先询问Helper。其实在接Uls产品的时候我们就建立了这里处理问题的流程见以下截图，我们有1线，2线（uls_helper）和研发，收集用户每一个信息并统计分析整理有共性的问题录入文档的FAQ中。有了流程的保障会发现FAQ整理的问题慢慢的增多，随着时间的推移用户可以社区内发出问题，并由其他用户以文档的形势进行内部闭环，释放产品的人力投入，形成良性的需求与供给，所以在文档中的FAQ是非常重要的一个环节。

文档中视频演示的重要性

对比日志竞品文档提供视频演示并不多，但是在运营日志产品的过程中发现了用户的习惯，这里再一次强调就是很多用户不习惯看文档，所以我们也尝试通过视频演示方式是否更好。在准备视频演示的过程中也发视频演示和产品文档是相辅相成的事，从最开始录制视频大约需要7分钟逐步优化文档结构和安装程序到最终将整个时间控制在3分钟左右，这也体现了准备视频演示对文档建设的推动作用。

最后，笔者觉得一个好的产品要尽量让用户少看文档，印象中看过一个文章说Iphone的开机按钮连不到一岁的小朋友知道去按并开机。希望每个人都是一个好的产品经理并作出更优秀的产品。