Blog: https://micleming.github.io/
近日对于敏捷中的轻文档，重沟通的做法中的轻文档，到底该如何把握轻的度略有疑惑。
敏捷软件开发宣言中有一条是：
工作的软件高于详尽的文档
为了能尽快交付产品给客户，并且从客户中获取反馈，这一条原则有很大的指导意义。但是轻文档并不意味着没有文档，只是如何把握文档的度是一个很难度量的事。在不同的公司，不同的团队，虽然都有在或多或少的跑着敏捷的工作流，但是对文档的度的定义却不尽相同。
首先来定义下这里所说的文档是指在一个团队中为了传递信息所能反复看的文字，而非一次性的快消品。
笔者曾经在百度、美团两个典型的国内互联网公司呆过三年，在这两个公司的团队学习/工作的过程中，发现他们的共有特点就是会比较看重文档的积累，特别是对于产品文档，需要有详细的产品说明。在工程师团队，也是鼓励通过wiki将相关的设计或曾经遇到过的坑积累下来，形成文档。可以说这已经是一种文化。现今笔者工作学习于ringcentral的厦门研发团队，团队按照比较纯粹的敏捷方式在跑，有明显的轻文档，重沟通文化，鼓励团队成员通过人与人的直接沟通的方式来进行信息传递，虽然会有文档，但是文档的量会被定义的比较低。所以希望对比两类公司的做法来求同存异，寻求到对于团队更好的做法。
接下来将从 文档的文化, 文档的价值, 文档需要包含什么 三部分进行讨论。
余秋雨老师曾对文化做过自己的定义：
文化是一种精神价值以及与此相呼应的生活方式，它的最终成果是集体人格
一个团队所崇尚的文化不同，对同一件事的看法也不同，它会影响在团队中所有人的工作方式和协作流程，所以这也是把文化拿到第一个来讨论的原因。
敏捷理念本质是重新把人放回到一切事务的核心，比如说不要用人/月来预估，减少文档，多沟通，和客户紧密的合作等等。
这是一种敏捷观念，我也认同这种观念，但减少文档是否有利于将人放到事务的核心，这点需要讨论。不可否认，有的软件公司将【人】视为一种资源，所以会以调度资源的方式去调度【人】这类资源，这是对人不尊重的做法。人生而自由平等，需尊重其独立意识。在某个运行的系统中，如果你想改进这个系统，或者打破原本系统中的一些非良性循环，甚至让这个系统出现自我进化的能力，那么需要引入一定的噪音，即不确定性因素。那么【人】便是一个不确定性的因素。然而，引入了这个不确定性因素后，如何让这个系统会朝着好的方向去改变，就需要对这个噪音做一定量的引导，如何引导也是需要进行讨论，当然这个引导的前提是尊重人的独立意识。
譬如，在团队的项目中，是否允许依据成员的看法来引入相背于目前团队技术栈的新技术，更直白的是假设团队的技术栈是react，并有了一定量的积累, 另一个成员觉得vue的技术体系会更适合目前的产品，是否允许将react替换成vue。然而，这里又会有一个问题，你觉得好，别人就觉得好么？如何解决这种冲突？或者如何对这个冲突进行引导甚至以此激发出正向的反馈？
回到文档的例子，轻文档的一个原因是：
通过文档能了解的事，你通过去询问，也能了解啊，而且添加了与外部世界的互动，通过文字传播的信息会导致阅读者与编写者无法有直接的互动，导致了人与外部世界的割裂。
然而，这里也会有一个问题：哪些东西是【人】希望与外界进行互动得到的，哪些是【人】仅仅希望通过阅读文字来了解的。这部分内容将在【文档需要包含什么】这部分进行讨论。
文字的价值是记录和传播。目前先暂且先将文档的使用者先局限在工程师团队。
在一个团队中，按照入职的时间顺序或者项目接手的时间长度，可以将成员分为新人和老人； 按经验的丰富程度和能力的高低可以分为高级工程师, 中级工程师, 初级工程师。不同的身份，对文档的需求也是不一样，文档所体现的价值也会不一样。文档的编写者一般为中高级工程师和老人的交集。
对于新人或者初级工程来说，当一个人入职一家公司，首先需要了解相关系统的使用，比如erp系统，hr系统等。接着需要了解实际工作中的相关资源如何申请，比如机器资源，代码权限等，再接着了解产品和代码的设计思路等。
对于老人或者中高级工程师来说， 可能需要回顾系统架构的历史设计思路，接口设计思路。
所以，对文档需求比较大的是新人和初级工程师，文档可以传递一些思考价值不大(相对于老人和中高级工程师交集人群)，但却必须要了解的东西。可以理解为这是一种工具，工程师团队，工具的一个极大的意义就是将工程师从无意义但却必须做的重复劳动中解放出来。
另，文档可作为一种契约，这里暂时不讨论
按照以上讨论，文档的重度使用者是新人和初级工程师, 那么他们需要什么，也就是考虑文档需要包含什么的重要依据。
在工程师团队，文档可以分为产品文档和技术文档。
在《用户体验要素》中，将一个产品的设计分为五层，分别为：
国内的pm一般工作在第二层和第三层，会有较为详细的功能规格设计和内容说明以及信息架构设计，在工程师开发产品过程中通常是通过阅读pm编写的产品文档来进行开发。 那一个新人初次接手一个产品的时候，应该会想要了解产品的价值及潜力(战略层), 产品提供了哪些服务(框架层), 产品的信息架构(结构层), 所以这些东西对于每个初次接触这个产品的人来说，是否是一样的？如果是一样，是否具有工具化的必要（文档可以理解为一种工具化的措施）？
在敏捷工作流中，会有一种成为AC(acceptance criteria)的东西，它的起始点是user story， user story 从用户的角度来对需求进行描述, AC 和 user story详细描述了一个产品的某一点的功能，然而它们有个缺点（也是优点），就是太详细了，导致几乎只能使用一次，无法重复阅读。
一个技术方案，必然是针对了某类问题而提出的方案，而这些问题，是进行顶层架构设计所需的要素。而了解这些问题也是理解一个现存技术架构的必要因素。而一个顶层的架构设计，必然是涵盖了某几个核心的设计模块，这几个某个阐述了解决某类问题的方案。所以，假设需要一份技术文档，那么它可能会涵盖以下几个部分：
用户手册必然是要有的，如何set up，有什么样的接口等。顶层设计和模块设计对每个新人，接收到的信息大致是一致的，这部分是进行口述传播还是文档化传播，我觉得应该取决于哪个效率高。
综上是关于文档的讨论。