作为一个初创技术公司，我司的信息管理水平，基本还停留在茹毛饮血的原始水平。领导让我给全公司的同事做一个分享，说是要提升一下文档意识的水位。作为一只热爱解决具体问题的攻城狮，竟然勉强我去讲“哲学”……瞬间化身嘤嘤怪。
不过转念回想起当年挥斥方遒，写作企业级信息管理系统初创方案构思的自己，现在给你个机会去实践，临了儿咋还退缩了呢？——没道理，干就完事儿了。
大家好，我是产品部的技术文档工程师，汪力迪。今天，将由我为大家带来一个关于文档的分享。一提到文档，可能很多同事会觉得，整个人都不好了，满脑子怨念，像是见到鬼——所以，我决定，把今天的分享命名为：文档什么鬼分享会。
作为一个人微言轻地“文档”工程师，来讲“文档”意识，难免有“王婆卖瓜”的嫌疑。所以在正式开始之前，想先抱一记大腿。
章淼老师是清华大学的博士，毕业后留校任教。教书多年，觉得象牙塔不接地气，想去企业历练几年，再回学校教书。于是，他跑到百度主持了BFE项目，然后就再没离开。回不去讲台的章老师依然好为人师，于是他在百度大学，面向研发工程师，开设基本研发能力教育的课程，《怎么写项目文档》就是其中之一。
在此引用一段，做个引子：
如果从代码的质量考察，我估计中国互联网圈合格的程序员不会超过20%；如果从项目文档的角度考察，中国互联网圈合格的程序员大概不会超过10%。和代码比起来，项目文档是一个更加严重的问题——几乎所有人都会认为代码是一个软件项目的产出；而只有很少的人会同意，文档也是一个软件项目的重要（甚至是不可或缺的）产出。
记得和某外国公司同行（也是中国人）聊起这个话题。
“你们需要写设计文档吗?”
“当然了，而且设计文档一定会经过严格的review。”
“那你在这里一定会感觉震惊的，很多即使是基础架构的系统都没有严格的设计文档”。
当我告诉对方这个情况的时候，我也很清楚，这绝不是一家公司的个案，而是一个普遍的情况。
公众号：章老师说怎么写项目文档
所以，在这里想表达的意思是：文档问题，是真实存在的。由于本次培训面向公司全员，所以在这里讨论的“文档”，本意上并不针对于研发文档；但由于个人经验所限，还是会更聚焦在自己比较熟悉的领域。
今天分享的内容，主要包括5个部分：
为什么要写文档：介绍文档缺失造成的问题，以及文档的重要性。
什么时候需要写文档：就我所知，介绍企业内部典型使用场景的文档类型。
如何管理知识和信息：文档，本质上是管理知识和信息的集合，而这些内容，对企业还是个人，都是宝贵的资产。
如何提升写作水平：简单说明一些与文档写作的基本思路和常识。
文档写作支持：大家可能对于文档工程师的具体工作不是很了解，所以在这里简单介绍一下我的职责，以及在整个文档系统中，可以给到大家的资源和支持。
那么现在，我们就正式开始。
我们经常可以听到各种关于文档的吐槽。（读稿）大家也是这么想的吗？（互动）所以实际情况真是如此吗？
文档没用，单纯为写而写？确实，文档的开发成本非常高。也正是因为如此，去定义要不要写一个文档，通常会慎重地考虑投入产出比。如果说是“没用的文档”，根本不会去开发；换句话说，只有真正被使用的文档，才会被定义。我们之所以常常感到“文档没用”，很多时候是因为，文档的质量不能满足使用需求，无法有效传递信息，不得不借助于口传身授，并不是文档本身没有用。
写文档是浪费时间，没时间写文档？根据章淼老师的介绍，对于研发文档而言，文档本身就是研发成本，代码时间只占研发时间的30%；写文档是整理思路的过程，打字的速度应该快于思考的速度；没有文档，后期会花费更多的维护成本。
研发都懂，没必要写？我们在策划对外交付的用户文档时，确实会要求用户具备某种程度的专业水平。但即便如此，也会以短板用户为准，不默认用户必然全知全能。
面对面交流效率高，不需要写文档？根据章淼老师的介绍，项目中，50%的时间是用来沟通。多人协作场景，1对多沟通场景，会出现沟通效率问题。所以随着公司规模越大，沟通成本也会成指数级地增加。
问题我已经考虑得很清楚，只是不会写文档？章淼老师认为，写不好文档的根本原因是“没想清楚”，提高文档写作能力的本质，实际上是提高分析问题的能力，提高设计系统的能力。
文档就是吹牛皮，要写得高大上？我们在这里讨论的文档不是市场文案，也不是创意文案，而是内部使用的文档。这类文档的主要作用是提高沟通效率，提升对“思考过程”的管理，所以客观实际才最重要，不需要加工创造，甚至连形容词都是尽可能避免使用的。
样式高于内容？很多人会认为，排版整齐一点，文档质量就更高——对于对外交付的文档，一定程度上，是的；对于内部使用的研发项目文档，则大可不必。之前我和很多研发同事沟通过文档问题时，会反复强调：我们首先看重的是内容质量，样式排版只是锦上添花。
文档都是给别人写的，对我有什么好处？其实，文档是一个知识和信息的生态，我们每个人都是互相输出价值；而且文档的目标是高效沟通，和知识积累，无论对公司还是对个人，都是宝贵的资产。
这里列出的问题，主要基于我个人比较熟悉的场景，在我看不到的地方，可能还会有更多挑战。
以解决上述问题为目的，文档体现出它存在的重要性。（念稿）
在这里我希望大家可以理解的是，我们写作文档，不仅是受迫于公司的要求，而是对我们每一个人都非常重要。
技术写作能力已经逐步成为技术人员的基本职业技能。通过写作，不仅帮助我们梳理思路、积累经验，实现高效沟通；通过阅读团队输出的文档，还可以使我们获得工作经验之外的成长，不断扩大能力圈；另外，大家也许都听过个人IP？其实我们每个人，尤其是专业/技术人员，非常适合建立自己的个人IP，这帮助我们走出去，在行业内进行更广泛技术交流与合作，在获得个人成长的同时，扩大个人影响力。而建立个人IP的最好方式，也是通过不断写作输出有价值的内容。
在座的大多数人，包括我在内，都是理工科专业毕业的。以前打着“学好数理化”的旗号，轻视文科好多年。现在，技术写作已经逐渐成为一门通识教育。国内很多知名院校，北大、复旦，都增加了相关专业；清华大学据说把技术写作与沟通，列为一项公共课程，我们公司有很多清华大学的校友，有兴趣的话，也可以了解一下。
这个部分讲得比较多，主要的目的是，希望大家能够理解，文档带给公司和我们自己的价值，以及提升写作水平，保证文档质量的重要性。接下来，让我们来了解下，哪些文档是“有用”的文档。
研发设计，这里主要指的是内部使用的文档，但实际上包含了很多，最终需要对外透出的内容。研发设计文档，可能是抱怨最多的文档：开发，使用，各有各的苦。因为痛点，所以重要，未来需要我们肯定是需要花大力气，把文档保障好。具体实现方法，后续我们会通过另外一个分享会，展开介绍。
由于我司产品复杂度较高，研发路径长，如何密切跟踪，高效协作，是个不小的挑战。
对外交付，主要包括2类。（念稿）但终归，很大程度上，倚赖于产品/研发输出相关信息。
流程规范，不用多说，大家都懂得。
上面提到的文档，可能是我们日常接触比较多的文档类型，涉及公司内部各个部门，需要我们每一个人共同努力，建设一个良好的生态。
接下来，我们再来深度地了解一下文档的本质。在这里需要先说明一下，知识、信息，以及与文档的关系。
其实，文档本质上是一种形式，承载了知识和信息。我们真正关心的不是文档，被文档固化了的知识和信息才是真正有价值内容。信息，是可以流动的内容，像一条河流，从一个人到另一个人，从一个部门到另一个部门；知识，是可以积累的内容，像万流归海。
信息的流动可以实现沟通和交流；知识的积累可以实现公司或个人的成长。搞清楚这一点，我们再来以全局视角看待文档管理，实际就是对知识和信息的管理。
那么，在公司内部，信息是如何流动的呢？
站在产品研发的立场环视周边，按照信息流入、流出的顺序，可区分为上游和下游。
上游，面向客户，是需求来源的地方，常由市场、销售等售前部门对接；下游，面向用户，是产品将要去向的地方，常由技术支持、运维等售后部门对接。
市场对接到客户，输出模糊的原始需求。
产品经理讲原始需求，进行分析分解，输出相对清晰的需求列表。
系统设计工程师针对需求列表，输出系统设计。
开发工程师基于系统设计输出详细设计，进行功能实现。
测试工程师基于系统设计输出测试用例，进行功能验证。
文档开发，主要指对外交付的产品配套文档，汇总研发文档相关内容，配套输出产品文档。
产品文档主要包括2种类型，面向上游的称为市场文档；面向下游的称为技术文档。
信息就是这样，在人与人，部门与部门之间传递。如果信息被歪曲了，怎么办呢？就像有一个团队游戏：第一个人看到词条，比划给第二个人；第二个人比划给第三个；以此类推；最后一个人猜词条是什么——通常，结果可以用“惊悚”来形容。
我们该如何避免出现惊悚的结果呢？
我根据自己的经验和理解，绘制了这张图：左边是知识来源，就是我们的研发部门；右边是我们最终触达的用户。在这个过程中：
研发知识系统：保存研发技术信息，包括但不限于：需求说明、系统设计、详细设计等。
内容管理系统：将对外交付文档常用技术信息解耦合成最小内容单元，便于后续重复使用。
技术文档系统：针对具体用户需求和使用场景，经内容设计后，讲内容管理系统的内容单元，经过重新组装，形成文档。
文档发布平台：将文档对外发布，并提供必要的查询服务和权限管理。
就我们目前来看，技术文档系统由产品部构建；文档发布系统在市场部；而研发知识系统和内容管理系统，基本上处于缺失状态。
如果要实现上面的知识/信息系统，结合到我司的具体情况，个人初步设想，整体来看，可能应该是这样的。
几个关键点需要考虑。那么具体实现，也是需要结合具体使用场景，做进一步细化设计，展开讨论。
第3部分主要介绍了一下文档系统的整体框架，不知道我有没有讲清楚。在座都是很聪明的头脑，设计过更加复杂的系统，想必理解起来应该是手到擒来。如果觉得有逻辑上不合理的地方，也欢迎交流。（互动）
具体到我们每一个人，如何通过接下来几页PPT的讲解，快速提升写作水平？——这还真是很有挑战，很想放弃。
首先，简单分享一下我个人认为，比较重要的点。
接下来快速过几页内容，摘自章淼老师的《怎么写项目文档》，主要是针对研发设计文档，但是主要观点大家也可以参考借鉴。
后续我们计划针对典型场景的常用文档，输出模板和写作说明，帮助大家充分理解写作思路。
写作水平的提升，最终还是依赖不断地练习。
很多同事，可能对技术文档工程师这个岗位，不太了解，不清楚我是做什么的，也不知道我能提供哪些支持，在这里正式介绍一下。
最后抛开岗位重新介绍一下我。这个是我的个人公众号，用来梳理和分享我的工作经验。我所在的领域有一个高大上的名字，叫做技术传播。技术传播，是一个新型小众的行业，主要解决产品和技术面向用户有效传递信息的问题，帮助用户更好地获取产品/技术信息。技术文档写作，是其中比较典型的一个形式。除此以外，还可以根据需求场景，采用视频教学、培训课程、用户帮助系统等其他形式。
用户，不局限于外部用户，内部用户也可以是我的服务对象。所以日常工作中，大家如果觉得遇到沟通效率低的问题期待改善，不妨找我一起想想办法。又或者想私下里交流一下技术写作和个人IP的经验，也随时欢迎。总之，我的slogan就是：大家的痛点问题，就是我的重点工作。
今天的分享就是这些内容，感谢大家的聆听。
其他推荐：
实施：GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播
这次他们说好要“讲真的” | 传播
在座都别吵了，你们还有我 | 技术传播
睿齐
技术传播从业者
品牌内容策划
自由摄影师
自由撰稿人
汪力迪
公众号：techcomm / htstory
微信号：bgrichi
邮箱：hash_0813@163.com
