程序员不喜欢写文档，如果有时间写文档，还不如把代码重构一遍。早前我也这么认为，究其原因，一则自己不喜欢也不擅长写文档，代码是给机器读的，只要语法和逻辑没问题，计算机就会听命执行，而文档是写给人看的，除了语法和逻辑，好文档还要照顾读者的心理感受；二则传统软件的客户对文档无感，它仅仅作为合同约定的交付物存在，客户压根就不会读这些文档，他们更依赖我们提供的现场培训和技术支持，让客户看文档自学太不符合甲方的身份了。
但现如今大部分软件产品都通过互联网向用户提供服务了，在线文档才是最高效的客户服务通道，我们熟知的那些开源软件都配有高质量的在线文档。好文档是优秀产品的标配，它不仅可以帮你带来更多的用户，而且还可以帮你服务更多的用户。作为互联网程序员的你，要是不懂如何写一份好的技术文档，都不好意思跟人打招呼，更别想做出好的产品。
好文档的评判标准是什么
无从下手，不知道从什么角度写，写些什么，这是我们经常遭遇的情况，那为什么会发生这种情况呢？通常是没有找到写作的意义，如果是为了交差而写，脑袋很容易卡壳，思路无法拓展。在敲键盘之前，我们先要想清楚这份文档是写给谁看的，通过这份文档可以帮读者解决什么问题。写作是我们输出影响力的一种能力，其最终目的是为了改变读者的信息、行为或信仰等，否则就是言之无物的垃圾。等明确了目标读者和意义之后，我们的思路也就打开了。
在想清楚这个问题之前，我们最好不要动手写文档，但真实情况是在不知道该写什么时，许多人就拿大量的实现细节来滥竽充数，包括代码片段和配置说明等，主要目的就是增加文档的篇幅，他的出发点不是用户需不需要，而是我擅长和熟悉什么，用户很容易被你的细节内容搞的不知所云。这就好比某个人的武艺很高，总爱在人前炫技，而不是在帮助他人解决问题的过程中显露自己的本领，通常这种人很遭人反感的。
编写技术文档的过程中会遇到哪些常见问题呢？通常我们习惯一上来就非常详尽地介绍这款产品有哪些特性，具体怎么安装、配置和使用等等，其实大部分潜在用户都是初次接触此类产品，他对我们的产品还没有完整的认知，压根不知道这款产品到底能帮他解决什么问题，对他而言有什么价值，一上来就深入细节就很容易把潜在用户搞蒙。
记得当年研究生毕业准备答辩幻灯片，导师给我们传授了一些经验：“答辩就是将自己的研究结果展示给评委，改变评委对这个研究课题上的认知，以及对自己的印象，从而获得较高的评分。幻灯片最好从Why开始，告诉评委这个研究课题的背景和意义，有了这个上下文做铺垫，评委才可能对你的研究感兴趣，才会跟随你了解后面的What和How。”
非功能特性是依附在功能特性上的，一款对用户毫无价值的产品，即使其非功能特性很优秀，那也引不起用户的兴趣。技术文档的开篇必须要通过介绍产品或方案的价值来跟用户建立连接，让他知道这款产品或方案跟他的工作是息息相关的，它可以帮助他优化工作。接下来才是让用户了解这款产品或方案是什么，以及怎么使用。这其实跟软件研发的流程类似，从用户需求开始，先分析梳理用户的痛点，再到产品需求，设计一款产品来解决用户的痛点，最后才是开发实现。
文档目录设计与用户思维
当我们明确了文档的目标读者，也明确了可以为读者解决哪些问题，写作本身就有了指向和价值，这样我们就可以调动身心和大脑，让自己文思泉涌，这就是用户思维。在此基础上，我们就可以开始考虑文档应该包含哪些内容，目录章节该怎样安排设计才更符合用户的学习规律。文档就是我们对外输出的一个产品，做产品就要学会换位思考，站在用户的视角考虑他们需要什么样的产品或方案，用户在技术选型时也是先确认产品或方案对其是否有价值，等他认可了这个价值之后才会进一步了解产品或方案的功能特性和使用方法。
今年上半年我们团队研发了一套微服务开发运维平台，下半年我们要把它推广给集团各个专业公司的研发团队，这时候我们就在思考目标用户当中哪些角色可以决定是否采用这款产品？通常是应用架构师，但他首先要了解这款产品的整体定位和作用，相较于其他同类产品有什么优势，这个阶段他不太关心产品的实现和操作等细节。另外，掌控感，或者说安全感，每个人都希望拥有的，那我们要帮用户建立这种感觉。在帮用户解决具体问题之前，我们要先搞定用户的情绪问题，让他在阅读文档时体验更佳。
如何帮用户获得掌控感或安全感呢？全景视图，让用户拥有上帝视角，从整体上把握产品或方案的情况，这个视图不会包含太多细节。就像要穿越一片热带雨林到达某个地方，如果一头就扎进森林里，那我们很容易就迷路了，最好是先爬上某处高地或树冠，从那里观察整片森林的情况，包括河流走向和地标特征等，掌握了这些信息之后我们就会更有安全感，更有把握走出这片森林。全景视图就像一个装载信息的框架，我们要先帮用户建立这个框架，后续再给用户介绍详细信息，这时候用户就可以把它们收纳进这个框架的不同位置，这样他就不轻易迷路了。因此，文档第一部分是产品概述，包括背景说明、功能定位和优势比较等等。
在对这款产品有了整体了解之后，那应用架构师这个角色接下来就要搭建一套演示环境了，以便对产品有更加感性的认知。这个阶段他不需要特别全面或深入地了解各种细节，只需要知道如何以最简单、最快速的方式把它配置运行起来，他可以借助这套环境给团队内的开发测试人员介绍这款产品。因此，文档第二部分是快速入门，主要是协助应用架构师把对概念理论的理解变成一套真实可见的演示环境。
通过上述两部分内容，我们让用户知道这款产品可以帮他解决什么问题，以及它是怎样运行的。接下来用户当中的开发、测试工程师等角色才会介入进来，他们需要深入了解产品的功能特性和使用方法，以便指导具体的编码实现。因此，文档的第三部分才是介绍产品特性的开发指南。不同角色的用户对文档有不同的需求，文档的章节目录设计要依照上述顺序来满足各类用户的需求。第四部分，除了知道怎样使用这款产品之外，用户还会关心在日常使用过程中怎样运营维护它，有没有一些配套工具或管理控制台，借助它监控微服务的运行情况，以及对微服务进行管控治理等等。第五部分，使用过程中遇到问题怎么办，尤其某些出现频率非常高的问题，这部分就要对这些常见问题做梳理，遭遇问题时方便用户查阅。
- 产品简介
- 快速入门
- 快速搭建环境
- 快速开发应用
- 开发指南
- 基础开发指南
- 进阶开发指南
- 扩展开发指南
- 操作指南
- 服务治理指南
- 网关配置指南
- 常见问题
- 经典案例
- 历史版本
- 下载说明
故事思维让文档不再枯燥
文档的章节目录设计要围绕用户需求：首先，我们要分析用户的类型，明确哪些类型的用户会先接触到这款产品；再者，说服了这批用户之后会带来哪些新类型的用户，这就是产品推广过程中接触用户的自然过程。在线文档的主要作用就是帮助我们获得新的用户，但我们必须要记住，推广产品是我们一厢情愿的想法，是站在我们的立场角度考虑问题，它是第二位的。写文档必须要先站在用户的立场角度，帮他们解决具体的问题，在解决问题的过程中顺便推销了产品，这才是用户思维的价值所在。
与用户思维同等重要的另一个思维模式叫做故事思维，这是人类大脑在漫长的进化过程中形成的生理特质所决定的，我们对故事类信息的接收会更加高效一些。如果你干巴巴地罗列产品功能特性，就像传统的产品使用说明书一样，那用户在阅读这份文档时是无感的，他会觉得枯燥无味、困难重重，无法将产品跟他遇到的问题联系起来。此时，我们就需要采用故事思维来组织包装这些素材，结合用户的使用场景讲故事。
故事思维的落地关键在于设计一个故事剧本，就像拍摄一部电影或者创作一本小说，你需要设计好每一幕的故事梗概，第一步干什么，第二步干什么，第三步干什么，...... 把每一步会出现哪些角色元素、这一步他们需要完成什么事情想清楚。那怎样设计这个故事剧本呢？窍门就是思考用户是怎样使用我们这款产品的，还是以微服务开发运维平台为例，我们在“快速入门 -> 快速搭建环境”章节就设计了这样一个剧本：
- 介绍微服务应用的标准架构
- 搭建微服务必备组件：注册中心
- 构建一个扮演Provider的微服务
- 构建一个扮演Consumer的微服务
- 搭建微服务必备组件：API网关
- 搭建微服务必备组件：配置中心
- 搭建微服务必备组件：治理中心
- 对照标准架构介绍演示环境
这个剧本是根据用户真实使用过程设计的，通过收集整理这些典型场景提炼出故事剧本，通过剧本组织各种素材。在阅读这份文档时，用户就会自然而然地代入到他真实的工作场景中，因为在用户脑海里原本就存在一些上下文，故事就是帮用户把上下文调度出来，这会有助于更好地理解文档，对文档可以带给他的价值有更清晰的认知。通过自助阅读文档解决了真实的问题，做到不求人会让他更有成就感。
故事线模拟用户学习过程
等故事的基本框架确定之后，我们就可以依次填充故事的各个部分，第一步该搭建哪个部件，第二步又该搭建哪个部件等等，一步一步层级递进，后续步骤依赖于前序步骤，从而构成一个向导式循序渐进过程，引导用户由浅入深、由易到难，这符合自然的学习过程，这样更容易让用户接受。
编写技术文档时有一种常见问题就是章节之间没有关联，彼此之间没有转承衔接，各部分内容比较零散，就像把不同主题的文章做成了杂文集。用户在阅读此类文档时思维很跳跃，刚看完一个内容，再看另外一个，这两者没有必然的联系。这其实也是没有站在用户角度思考问题，用户跟我们不一样，他对产品或方案不像我们这样熟悉，缺少我们所掌握的隐性信息，章节内容上的跳跃加重了用户阅读文档的难度。最好就是找到一条线索将每个章节的内容衔接起来，就像章回体小说一样，看完这章想下章。借鉴Oracle JDK的示例工程宠物商店(Java Pet Store) ，我们也设计了一个简单但完整的用户信息管理服务来贯穿整个故事。
进阶式设计跨越学习曲线
在文档内容编排方面，我们不要一次性让用户学习太多新东西，向导里每个步骤的内容分布，必须要符合进阶式的学习模型，一下子给用户展示太多信息，只会把用户搞懵圈，让他产生畏难的情绪，对学习丧失兴趣。每个小节的内容不能填充的太多，尽量控制在十五分钟到半个小时以内，用户只要稍稍努力就可以完成挑战，这样用户就会感受到学习的乐趣，小步快跑，每一次小小的进步都可以激励自我，这样他就有信心自助式地完成整个系统的学习了。这样的学习方式是符合人性的，符合学习心理学的。
近段时间参与外部客户项目写标书，刚开始大家都无从下手，打不开思路，想着从网络上摘抄一些内容粘贴进去，但这样写作味同嚼蜡，写的不开心，读的也没感觉。后来就想到我们必须要揣摩读者，想象对面就坐着读者。标书的读者是跟我们一样在专业领域有着丰富经验的评委，我们没有必要向他讲解任何概念性的内容，在标书中我们只需要围绕客户的问题提供解决方案，简明扼要，点到为止，这样即是对评委的尊重，也是体现我们的专业性，我们不是出售文字，而是出售专业经验，就是有个流传甚广的故事里说的，一个专家被请去给工厂诊断故障原因，他在工厂里转了一圈只用粉笔花了一个叉叉，就挣了十万美金。
不同的读者要采用不同的沟通方式，除了要清楚读者的角色和能力等级，还要知道自己在这次对话中扮演的角色，俯视时要就低不就高，仰视时也要就低不就高，平视时做到点到为止，即读者的能力水平跟自己相似，那就要做到简明扼要、切中要害。从读者角度看，照顾对方的心理，让他感到舒服就对了。
不同视图服务不同的用户
那你可能会说，除了新用户还有许多老用户需要看在线文档，上述这种设计是否符合他们的使用习惯了呢？针对不同类型的用户，我们必须要提供不同的视图，或者说不同的入口，例如按照产品的功能特性建立一个索引视图，类似Hao123一样的导航页面，或者提供一个搜索框，深度用户对我们的产品已经非常熟悉了，他们可以通过这些入口快速找到他们想要的内容，从而更加高效地使用这份文档。同样的内容通过不同的组织方式呈现给不同的用户，这就是视图法带给我们的价值，横看成岭侧成峰，远近高低各不同。
实战
基于三个原则：
- What：是什么，解决了什么问题。
- Why：为什么采用这个，技术选型对比，优缺点
- How：如何下手...
