前言

如何写这篇分享，本身就是一次分享。

正文

为什么要些写文档？

1、让初次接手业务的同学有一个大概了解；
2、作为自己的备忘录，减轻记忆的负担，也方便后续快速跟进；
3、先从宏观角度来思考完备性，实现过程中可以作为指引；
4、方便其他同学来提出建议，共建和谐社会；
5、和团队其他角色沟通用时，脑海关于需求的千丝万缕先用文字、图表描述出来，在沟通过程中就可以精确的描述和表达，再具体讨论有疑问的点，最后勾勒出整个需求的蓝图；
...

在工作过程中遇到很多问题，解决这些问题的过程中会积累经验和见识，写文档就是把这些知识进行抽象、整理，继而沉淀下来。当我们再次遇到类似的问题，我们就能快速在脑海、文档中检索出来对应的解决方案。

要写什么文档？

信息是数据的组合排列，比如微博上每日最新的资讯，朋友圈不断更新的动态。
知识是大脑对信息的组合与整理，对别人而言的知识，对自己可能只是信息。
信息经过大脑的整合，组织出自己能够理解的知识并沉淀下来，则成为个人的知识、团队的文档。

写文档的几个思路：
太简单的不写； ==> 浪费时间；
自己不熟悉的不写； ==> 误人误己；
炫耀性的文章不写； ==> 蹉跎岁月；
没有总结的不写； ==> 先思考后产出；
看完没有收获的不写； ==> 没有价值；

按照这个思路，我常写的文档以下几种：
1、方案设计文档——方案评审用；
2、经验总结文档——抽象避免重复采坑；
3、问题处理文档——专项问题跟进；
4、知识提炼文档——深入学习；

这些文档里面有分享价值的内容，我都会脱敏后发布出来，这样也是日常更新的主要来源。
写文档的目标是掌握知识，并不是简单的信息积累，更多是组合、整理、思考、启发。

怎么写文档？

1、明确此篇文档的目标人群；
以技术方案评审文档为例，文档的目标人群是参与评审的技术同学，所以描述需要更加抽象，避免出现大量的细节；
以反馈问题跟进文档为例，文档的目标人群是运营、产品、开发等，所以需要针对特定的逻辑，用通俗的语言去描述问题的前因后果，避免出现代码逻辑和无法理解的词汇；

2、理清要表述问题的中心；
技术方案评审文档，是为了阐述技术方案的整体设计；
反馈问题跟进文档，是为了针对某个问题给出结论；

3、梳理整个描述逻辑；
以技术方案评审文档为例，大致流程可以是 介绍背景=》问题思考=》抽象提炼=》思考总结；
以反馈问题跟进文档为例，可以是 问题表现》问题分析》出现原因》修复方案》后续问题》质量监控；

4、善于用图；
描述功能、逻辑的基本过程，用流程图；
描述实现过程中的模块关系，用模块结构图；
描述逻辑功能下的数据变化，用数据流图；
描述随着时间的状态变动，用时序图；
...

设计的时候要有分层的思想，比如说分UI层和数据层。在思考整个功能的时候，可以把客户端通过接口请求到的数据当成物料。把数据展示出来，用户会进行操作，有可能会影响数据本身。把原始物料和生成的数据通过埋点等通知后台，就是一个反馈的过程。
粗细有度，方案评审尽可能屏蔽实现细节，经验总结则要仔细回顾遇到的问题。
模块化的思想同样很重要，用模块来抽象分析需求，可以更好屏蔽实现细节，整理出模块间的依赖，再用接口（方法）等来描述模块间相互的调用，这样也有助于功能的扩展分析和模块细化。

以某业务的视频播放为例，我们可以抽象出来哪些模块？
a.底层播放器模块，处理底层的播放逻辑；
b.封装播放器模块，对模块a的封装，根据业务需要调用模块a；
c.具体业务逻辑模块，这里目前可以细化出业务视频模块A、业务视频模块B等；
d.全局播放控制模块，处理多个c模块之间的内容传递、播放控制协调等；
e.扩展的播放打断模块，处理闪屏、音频等等多业务逻辑的兼容；

接下来把模块间的处理进行抽象。
a模块只被b模块调用，大概有play/pause/stop等接口；
b模块只被c模块调用，c模块会有较多交互细节，比如说滑动的时候触发自动播放、进入时候会自动播放、划出屏幕触发暂停等，为了更好区分场景可以区分为autoPlay(自动播放）、manualPlay（手动点击播放）、pause等接口；
同理，再梳理出来c、d、e等模块之间的关系，这样出来一个整体的设计，实现的过程就可以按图索骥。
如果出现异常场景，第一反应是回顾这个设计图，思考这种问题是否在自己当初的设计场景里面，如果是那么有没有考虑解决方案；如果设计没有考虑这种case，那么应该从哪些模块去解决，可能会造成哪些影响。通盘考虑完之后，重新改动设计，最后才是代码实现。
有哪些模块、模块之间的依赖和调用，后续如何新增和修改模块，都是方案设计和评审的关注重点。

总结

文档很难尽善尽美，问题是解决不完，而成长也是永无止境。
当我们养成写文档的习惯，我们就已经迈出了第一步。
只要保持写文档，我们就必须去思考、总结，自然可以从工作中学习到更多知识。