如何写出好的产品帮助文档？

程序员不喜欢写文档，若是有时间写文档，还不如把代码重构一遍。早前我也这么认为，究其缘由，一则本身不喜欢也不擅长写文档，代码是给机器读的，只要语法和逻辑没问题，计算机就会执行，而文档是写给人看的，除了语法和逻辑，好文档还要照顾读者的心理感觉；二则传统软件的客户对文档无感，它仅仅做为合同约定的交付物存在，客户压根就不会读这些文档，他们更依赖咱们提供的现场培训和技术支持，让客户看文档自学太不符合甲方的身份了。

但现现在大部分软件产品都经过互联网向用户提供服务了，在线文档才是高效的客户服务通道，咱们熟知的那些开源软件都配有高质量的在线文档。高质量文档好产品的标配，它不只能够帮你带来更多的用户，并且还能够帮你服务更多的用户。做为互联网程序员的你，要是不懂如何写一份好的技术文档，都很差意思跟人打招呼，更别想作出好的产品。

• 好文档的评判标准是什么

无从下手，不知道从什么角度写，写些什么，这是咱们常常遭遇的状况，那为何会发生这种状况呢？一般是没有找到写做的意义，若是是为了交差而写，头脑很容易卡壳，思路没法拓展。在敲键盘以前，咱们先要想清楚这份文档是写给谁看的，经过这份文档能够帮读者解决什么问题。写做是咱们输出影响力的一种能力，其最终目的是为了改变读者的信息、行为等，不然就是言之无物的。等明确了目标读者和意义以后，咱们的思路也就打开了。

在想清楚这个问题以前，咱们不要动手写文档，但真实状况是在不知道该写什么时，许多人就拿大量的实现细节来滥竽充数，包括代码片断和配置说明等，主要目的就是增长文档的篇幅，他的出发点不是用户需不须要，而是我擅长和熟悉什么，用户很容易被你的细节内容搞的不知所云。这就比如某我的的本领很高，总爱在人前炫技，而不是在帮助他人解决问题的过程当中显露本身的本领，一般这种人很遭人讨厌的。

编写技术文档的过程当中会遇到哪些常见问题呢？一般咱们习惯一上来就很是详尽地介绍这款产品有哪些特性，具体怎么安装、配置和使用等等，其实大部分用户都是初次接触此类产品，他对咱们的产品尚未完整的认知，压根不知道这款产品到底能帮他解决什么问题，对他而言有什么价值，一上来就深刻细节就很容易把用户搞蒙。

记得当年研究生毕业准备答辩幻灯片，导师给咱们传授了一些经验：“答辩就是将本身的研究结果展现给评委，改变评委对这个研究课题上的认知，以及对本身的印象，从而得到较高的评分。幻灯片要先从Why开始，告诉评委这个研究课题的背景和意义，有了这个上下文铺垫，评委才可能对你的研究感兴趣，才会跟随你了解后面的What和How。”

非功能特性是依附在功能特性上的，一款对用户毫无价值的产品，即便其非功能特性很好，那也引不起用户的兴趣。技术文档的开篇必需要经过介绍产品或方案的价值来跟用户创建链接，让他知道这款产品或方案跟他的工做是息息相关的，它能够帮助他优化工做。接下来才是让用户了解这款产品或方案是什么，以及怎么使用。这其实跟软件研发的流程相似，从用户需求开始，先分析梳理用户的痛点，再到产品需求，设计实现一款产品来解决用户的痛点。

• 文档目录设计与用户思惟

当咱们明确了文档的目标读者，也明确了能够为读者解决哪些问题，写做自己就有了指向和价值，这样咱们就能够调动身心和大脑，让本身文思泉涌，这就是用户思惟。在此基础上，咱们就能够开始考虑文档应该包含哪些内容，目录章节该怎样安排设计才更符合用户的学习规律。文档就是咱们对外输出的一个产品，作产品就要学会换位思考，站在用户的视角考虑他们须要什么样的产品或方案，用户在技术选型时也是先确认产品或方案对其是否有价值，等他承认了这个价值以后才会进一步了解产品或方案的功能特性和使用方法。

今年上半年咱们团队研发了一套微服务开发运维平台，下半年咱们要把它推广给集团各个专业公司的研发团队，这时候咱们就在思考目标用户当中哪些角色能够决定是否采用这款产品？一般是应用架构师，但他首先要了解这款产品的总体定位和做用，相较于其余同类产品有什么优点，这个阶段他不太关心产品的实现和操做等细节。另外，掌控感，或者说安全感，每一个人都但愿拥有的，那咱们要帮用户创建这种感受。在帮用户解决具体问题以前，咱们要先搞定用户的情绪问题，让他在阅读文档时体验更佳。

如何帮用户得到掌控感或安全感呢？让用户拥有全景，从总体上把握产品或方案的状况，这个视图不会包含太多细节。就像要穿越一片热带雨林到达某个地方，若是一头就扎进森林里，那咱们很容易就迷路了，应该先爬上某处高地或树冠，从那里观察整片森林的状况，包括河流走向、标志性地貌特征等，掌握了这些信息以后咱们就会更有安全感，更有把握走出这片森林。全景视图就像一个装载信息的框架，咱们要先帮用户创建这个框架，后续再给用户介绍详细信息，这时候用户就能够把它们收纳进这个框架的不一样位置，这样他就不轻易迷路了。所以，文档开头部分是产品概述，包括背景说明、功能定位和优点比较等等。

在对这款产品有了总体了解以后，那应用架构师这个角色接下来就要搭建一套演示环境了，以便对产品有更加感性的认知。这个阶段他不须要特别全面或深刻地了解各类细节，只须要知道如何以最简单、最快速的方式把它配置运行起来，他能够借助这套环境给团队内的开发测试人员介绍这款产品。所以，文档下一部分是快速入门，主要是协助应用架构师把对概念理论的理解变成一套真实可见的演示环境。

经过上述两部份内容，咱们让用户知道这款产品能够帮他解决什么问题，以及它是怎样运行的。接下来用户当中的开发、测试工程师等角色才会介入进来，他们须要深刻了解产品的功能特性和使用方法，以便指导具体的编码实现。所以，文档的第三部分才是介绍产品特性的开发指南。不一样角色的用户对文档有不一样的需求，文档的章节目录设计要依照上述顺序来知足各种用户的需求。第四部分，除了知道怎样使用这款产品以外，用户还会关心在平常使用过程当中怎样运营维护它，有没有一些配套工具或管理控制台，借助它监控微服务的运行状况，以及对微服务进行管控治理等等。第五部分，使用过程当中遇到问题怎么办，尤为某些出现频率很是高的问题，这部分就要对这些常见问题作梳理，遭遇问题时方便用户查阅。

1. 产品简介
2. 快速入门
   2.1 快速搭建环境
   2.2 快速开发应用
3. 开发指南
   3.1 基础开发指南
   3.2 进阶开发指南
   3.3 扩展开发指南
4. 操做指南
   4.1 服务治理指南
   4.2 API Gateway 配置指南
5. 常见问题
6. 经典案例
7. 历史版本
8. 下载说明复制代码

• 故事思惟让文档再也不枯燥

文档的章节目录设计要围绕用户需求：首先，咱们要分析用户的类型，明确哪些类型的用户会先接触到这款产品；再者，说服了这批用户以后会带来哪些新类型的用户，这就是产品推广过程当中接触用户的天然过程。在线文档的主要做用就是帮助咱们得到新的用户，但咱们必需要记住，推广产品是咱们一厢情愿的想法，是站在咱们的立场角度考虑问题，它是第二位的。写文档必需要先站在用户的立场角度，帮他们解决具体的问题，在解决问题的过程当中顺便推销了产品，这才是用户思惟的价值所在。

与用户思惟同等重要的另外一个思惟模式叫作故事思惟，这是人类大脑在漫长的进化过程当中造成的生理特质所决定的，咱们对故事类信息的接收会更加高效一些。若是你干巴巴地罗列产品功能特性，就像传统的产品使用说明书同样，那用户在阅读这份文档时是无感的，他会以为枯燥无味、困难重重，没法将产品跟他遇到的问题联系起来。此时，咱们就须要采用故事思惟来组织包装这些素材，结合用户的使用场景讲故事。

故事思惟的落地关键在于设计一个故事剧本，就像拍摄一部电影或者创做一本小说，你须要设计好每一幕的故事梗概，第一步干什么，第二步干什么，第三步干什么，...... 把每一步会出现哪些角色元素、这一步他们须要完成什么事情想清楚。那怎样设计这个故事剧本呢？窍门就是思考用户是怎样使用咱们这款产品的，仍是以微服务开发运维平台为例，咱们在“快速入门 -> 快速搭建环境”章节就设计了这样一个剧本：

1. 介绍微服务应用的标准架构
2. 搭建微服务必备组件：注册中心
3. 构建一个扮演Provider的微服务
4. 构建一个扮演Consumer的微服务
5. 搭建微服务必备组件：API Gateway
6. 搭建微服务必备组件：配置中心
7. 搭建微服务必备组件：治理中心
8. 对照标准架构介绍演示环境复制代码

这个剧本是根据用户真实使用过程设计的，经过收集整理这些典型场景提炼出故事剧本，经过剧本组织各类素材。在阅读这份文档时，用户就会天然而然地代入到他真实的工做场景中，由于在用户脑海里本来就存在一些上下文，故事就是帮用户把上下文调度出来，这会有助于更好地理解文档，对文档能够带给他的价值有更清晰的认知。经过自助阅读文档解决了真实的问题，作到不求人会让他更有成就感。

• 故事线模拟用户学习过程

等故事的基本框架肯定以后，咱们就能够依次填充故事的各个部分，第一步该搭建哪一个部件，第二步又该搭建哪一个部件等等，一步一步层级递进，后续步骤依赖于前序步骤，从而构成一个向导式按部就班过程，引导用户由浅入深、由易到难，这符合天然的学习过程，这样更容易让用户接受。

编写技术文档时有一种常见问题就是章节之间没有关联，彼此之间没有转承衔接，各部份内容比较零散，就像把不一样主题的文章作成了杂文集。用户在阅读此类文档时思惟很跳跃，刚看完一个内容，再看另一个，这二者没有必然的联系。这其实也是没有站在用户角度思考问题，用户跟咱们不同，他对产品或方案不像咱们这样熟悉，缺乏咱们所掌握的隐性信息，章节内容上的跳跃加剧了用户阅读文档的难度。最好就是找到一条线索将每一个章节的内容衔接起来，就像章回体小说同样，看完这章想下章。借鉴 Oracle JDK 的示例工程宠物商店(Java Pet Store) ，咱们也设计了一个简单但完整的用户信息管理服务来贯穿整个故事。

• 进阶式设计跨越学习曲线

在文档内容编排方面，咱们不要一次性让用户学习太多新东西，向导里每一个步骤的内容分布，必需要符合进阶式的学习模型，一会儿给用户展现太多信息，只会把用户搞晕，让他产生畏难的情绪，对学习丧失兴趣。每一个小节的内容不能填充的太多，尽可能控制在十五分钟到半个小时之内，用户只要稍稍努力就能够完成挑战，这样用户就会感觉到学习的乐趣，小步快跑，每一次小小的进步均可以激励自我，这样他就有信心自助式地完成整个系统的学习了。这样的学习方式是符合人性的，符合学习心理学的。

近段时间参与外部客户项目写标书，刚开始你们都无从下手，打不开思路，想着从网络上摘抄一些内容粘贴进去，但这样写做味同嚼蜡，写的不开心，读的也没感受。后来就想到咱们必需要揣摩读者，想象对面就坐着读者。标书的读者是跟咱们同样在专业领域有着丰富经验的评委，咱们没有必要向他讲解任何概念性的内容，在标书中咱们只须要围绕客户的问题提供解决方案，简明扼要，点到为止，这样便是对评委的尊重，也是体现咱们的专业性，咱们不是以文为生，而是依靠专业经验，就是有个流传甚广的故事里说的，一个专家被请去给工厂诊断故障缘由，他在工厂里转了一圈只用粉笔花了一个叉，就挣了十万美金。

• 不一样视图服务不一样的用户

那你可能会说，除了新用户还有许多老用户须要看在线文档，上述这种设计是否符合他们的使用习惯了呢？针对不一样类型的用户，咱们必需要提供不一样的视图，或者说不一样的入口，例如按照产品的功能特性创建一个索引视图，相似导航页面，或者提供一个搜索框，深度用户对咱们的产品已经很是熟悉了，他们能够经过这些入口快速找到他们想要的内容，从而更加高效地使用这份文档。一样的内容经过不一样的组织方式呈现给不一样的用户，这就是视图法带给咱们的价值，横当作岭侧成峰，远近高低各不一样。

• 经常使用开源或免费文档工具

文末再推荐几款平常写做用的软件工具：

• 闪念胶囊：锤子科技出品，支持语音录制和识别，好处是能够很是便捷地记录本身的想法，尤为是当你灵光一闪的时候，键盘和纸笔都没有语言表述来的快，本文的主体内容都是借助它完成的。
• 锤子便签：锤子科技出品，它是我在手机上码字最喜欢用的工具，纯粹到让你有写做的意愿。
• 印象笔记：支持手机和电脑之间同步，在手机上写到一半的文档能够在电脑上继续写，反之亦然，作到无缝衔接，不会由于切换工具就影响了写做的连续性。
• MWeb Lite：MacBook上编辑Markdown文本工具，免费易用，手机上我就用网易的有道笔记。

技术人习惯从本身角度看问题，产品人习惯从用户角度想问题，技术人也要掌握产品思惟，用户思惟和故事思惟是很是有效的两套方法，市面上有不少经典书籍介绍它们，感兴趣的朋友能够找来看一看。另外，你们也能够关注个人微信公众号，里面有很多相关内容，对咱们作好技术工做有很是大的帮助。

今天先分享到这里，若是你以为有价值，麻烦动动手指 转发 给其余须要的小伙伴。另外，老兵哥我后续还会分享职业规划、应聘面试、技能提高、影响力打造等经验，欢迎 关注 本博客或公众号「 IT老兵哥 」！