第一篇算是一个导论

不知道大家有没有经常回溯、追溯或者抱怨过这样的内容。

1. 第一种抱怨：工作了4年、5年，晋升不明显，最最多做到一个小Team Leader，管了3-5个人。跳来跳去工资增涨只不过多个2千、3千。而眼看着快有希望一年突破50万时，已经35，36了。然后一旦公司有一个什么风吹草动，就等着被优化了。天天受到这样的心灵“煎熬”。
2. 第二种抱怨：天天我们PM、我们老大要我们写文档，文档我是写了，可是我不是作协的啊，我交付的是代码不就可以了，写这种东西有什么用呢？要看文档？不如去看代码。
3. 第三种抱怨：这家公司、这个团队一塌糊涂，没文档、没传承，一切靠口口相传，做3个月我可以离开这个团队了，这简直就是一个“坑”。
4. 第四种抱怨：每次开会被大老板骂，要做点事先要写文档，直接不可以上代码吗？那个XXX有什么了不起的，不就是PPT做了好吗？
5. 第五种抱怨：唉呀这个什么对接第三方，文档一陀XXX，什么都没有，一会变一会变，刚调试通过的东西和他们给的文档相差巨大；

基本就这5大类抱怨占到了平时工作的90%。

很多人可能不知道，技术文档的写作有多重要！重要的什么程度呢？如果说你的技术能力占到了50%，文档的工作也是占到了50%，如果你是在一些大型点的或者是甲方型企业工作，文档的这一块工作能力甚至是占到了60%的重要程度，和技术能力的占比就长江商学院探讨过的一个话题来说，文档功夫对比技术能力是达到了六比四开。

程序员知道文档很重要，可是每次在培养文档能力和培养技术能力时，有90%以上的程序员们情愿选择了有时间去看一个语言、一个技术点、而忽略了文档写作能力的培养。

难道我们培养的都是一群“连话都不会说的”真的猿吗？不是，我们的语文教育贯穿了幼儿园、小学、初中、高中，长达10几年，不少211、985还是有大学语文的，特别是大一、大二，如果大学语文挂了是不可能毕业的。

笔者因为工作原因，接触过上百个供应商、友商，交往和有交集、工作上配合的程序员、架构也超过了万人，但是看到了太多清华、北大、复旦的尖子生，写个文档逻辑不清、颠三倒四，交给别人看别人直接一脸的懵。。。

知道文档写作能力的重要性为什么程序员们还这么不去有意培养自己的能力呢？这源于以下几个原因造成。

造成程序员写作能力差的原因分析

觉得技能点的提升不如文档描述能力的提升有价值

很多程序员比较淘醉于网上的一些技能点，什么redis锁啦、抢红包啦、秒杀啦、JDK的new features啦。

没错，这些点很重要。还学你连饭都没得吃了！但是这些点不能够直接为你带来个人能力上暴发式增涨。请注意“暴发式增涨”这5个字。即一年后你的工资待遇是准备好50%这么一翻的能力，而不是说什么跳个槽涨个30%，这个太简单了。如果这边有人说我这边拿3千我出去了拿8千，这个抬杠就没意思了。

暴发式增涨怎么理解呢？那就是：如果你跳脱了写增、删、改、查的企业级IT（包括大厂，大厂也是增删改查+数据库+非数据库而己）你能作什么？如果你40了你还是高级工程师时你可以干什么？

这两个问题如果可以轻而易举的自我回答，你的工资就会暴发式增涨。因为文档能力就是取代你的敲代码能力的一种综合能力。此处的“文档”能力是综合软实力的代称而己。

具有这样思维的程序员们属于比较典型的固步自封。

看文档不如读代码去

这种程序员也得不到上升？为什么呢？说出这种话的人甚至不能够作为一个team leader。因为leadership中有一项非常重要的能力，即：PDCA环能力。

说文档哎？和PDCA环有什么毛线关系呢？不然！请耐心看下去。

PDCA环是基本的Leader能力，因为很久。。。久在福特公司的第一辆汽车诞生之时世界的企业界就开始提出如何培训员工，要培训员工仅仅只是带着他带6个月就行了吗？带3年？这种叫“死带”，没用的，带、培、管员工成熟的做法是

1. 你先要和你的下属共同制定计划。
2. 制定完计划后没完呢，你要让他明白这份计划为什么要这么制定，其中每一个步骤到底是用来干什么、解决什么痛点的；
3. 你不能替手下、替员工去做。一种是万事亲历亲为行领导要不得，这种领导容易把自己做成瓶劲。另一种就是什么都不去管的领导，你好我好大家好，这种领导会把企业作废。这就是一个度的把握了，因此一般来说好的领导会如此行事：教一遍、让员工照着做一遍、然后给一个同样的类型但内容不同的活让员工做一遍。
4. 做完了就好了吗？你要去不断的check他的成果，以结果为导向。告诉他这样做是好了还是错了？错在哪？为什么？
5. 逐步放手，最终如雏鹰的第一次“试飞”、“放单飞”后也只是把这个check、跟踪和及时反馈给到员工他的成果是怎么样的这么一个频率放长而己。

这就是标准的leader要做到的最最基本的点，现在你碰到你手下有一个leader或者你遇到了你们的leader，他在一个团队一个公司至少存在了2年以上了，对着你来一句：文档没必要，自己看代码吗？

嘿嘿嘿，作为领导、作为这个leader下属，请问你是什么感想？想想一开始我总结的5种抱怨？是不是？

那么到底是代码注释重要还是文档重要呢？

这边客观的告诉你：都重要，但又要区分一个“度”的问题了。下面开始敲黑板了，加粗文字很重要：

1. 如果只是一个30行，40行的代码，而你的工程就这么一个东西。请你对类的作用、文法名、返回值、语句块内的for、while、if-else分支、抛错都做注释即可；
2. 如果是参与模块开发、接口对接，那么你除了第1点中的那些注释外你必须要把：设计方法、系统边界、模块边界、逻辑交互、接口文档、同步还是异步、是否有schedule那么schedule是怎么设置的、属性配置文件里每一行是干什么的、如果有超过2个以上的类那么每个类是什么作用、启动时有什么加载、数据库表关系、redis里存的key的名字数据结构失效时间等等这些框架级的东西，我们不说需要多少beautiful，你至少拿个文本文体1，2，3，4这样一行行列在那边也可以呀？这能花你1小时吗？就算 花你1小时，这1小时你都不去记你参与什么模块化设计、编程呢？换了我碰到这样的人，那我会让你天天只改BUG，但是改BUG你也要在Jira里写为什么会造成这个bug和贴图呀，对不？这也是cmmi3基本要求的；

凡事要讲究一个度、一个边界。我们可以去看tomcat源码或者spring源码。spring源码是有详细的类与类间的class diagram、sequence、use-case的UML图的。而且spring的源码里的注释可以到达某个方法、某个参数有哪些不同的类型每种类型的传入又会引起什么样的结果，很多看过开源软件源码的人知道注释的量基本上和源代码的量为1：1的比例，有时甚至注释超过了源代码的量。

这也是文档啊？因此。。。什么叫文档没必要直接读源码？这本身就是错误的观点。

个人或者是企业因为主观行为意识疏忽了文档功底的培养

知道技术文档的重要性，可是就是不知道该如何去写？公司、团队也知道一直以来IT团队缺文档，可是领导就是不断的强调：要文档，要文档，甚至骂了娘。但也不知道如何去培养。

这也是因为很多时候业务驱动型公司的性质导致的。很多时候包括大厂都是业务导向型公司天天做业务功能开发，因为这些业务功能可以引流、可以增单、可以拉风投。而这些时间已经花掉了程序员们平时绝大部分的时间了。

当两个培训方案报到老板手里或者是部门主管手里，一个是培训presentation能力，一个是培训某个技能点，而这个技能点在3周内就可以带来实际业务收益，领导肯定会选择硬技能培训。同时硬技能也更容易培训，它可以达到短期内的效果。

而软技能的培训通常是要中长期才会出现效果且无专门的对口的培训，这钱花了很多企业、个人都觉得“不值”。

以上问题没有错，错在：疏忽。

我们先提一个点：既然知道了重要性，时间总是可以挤得出来了。提高效率的同时，每个月抽4课时5课时（小时）难道没时间吗？

个人来说：工作占满了我8小时，我哪有时间写文档。

这又是一个意识的问题。

你高中入学后为了三年后冲刺高考，你一天难道就学8小时吗？而且是明知对自己1年、两年后会起到至关重要的效果的东西你还不去学？打游戏有时间吗、泡MM有时间哈、摸鱼也有的是时间哈。

每天自己有意识的额外的去写点文档、甚至没人让你写时你自己也去写写看，每天额外的2小时会要了自己的命吗？当日积月累、月复一月、年复一年，量变到达了质变，人和人之间的差距就此拉开了。

关键的还是在于“自己”，这个世界没有人会去阻止你你想要干的事！通往成功的道路的唯一障碍只有“自身”，至于方法论，也正是这个系列要教给大家的。

道理都懂、话不多说，后面系列会上干货

我们举一些实例吧。

伟大的数学家、诗人、文豪。“三十年前在贵州，曾因奇异点生愁。如今老去申江日，喜见故人争上游。”开篇《射影几何概论》惊为天人，《湄潭吟社诗存第一辑》品茶论道忧国忧民。当别人问他为什么你一个搞纯数学的要去学文学。苏步青笑笑说：科学是为人民大众作服务和普惠的，如果你的技术、你的学术不为普通大众所能接受，这个技术有用吗？如果一个人数理化要学得好，他的语文必须要学的好。所谓语文就是你的逻辑、抽象思维。因此我常用“碎片化”学习方法来补我自己的语文。

大散文学家，他本业是地质学，“崎岖五岭路，嗟君从我游。峰峦隐复见，环绕湘水头。风云忽变色，瘴疠蒙金瓯。山兮复何在，石迹耿千秋。”短短40字悼念其学生，堪称语简情深，感人肺腑。

这不是个文学家吗？NO。。。他是科学家。科学幻想小说并非从凡尔纳开始，但在幻想的规模上，特别是在科学的语言性上，凡尔纳大大超过了前人。凡尔纳的才能在于，他实际上是在科学技术所容许的范围里，根据科学发展的规律与必然的趋势做出了种种在当时是奇妙无比的构想。因为这些构想符合科学的发展趋势，他们到了20世纪几乎全都成为了现实。凡尔纳对于科学的态度是严肃认真的，他尽可能把自己的想象建立在科学的基础上，例如，为了写从地球飞行到月球的故事，他就是先仔细研究过空气动力、飞行速度、太空中的失重以及物体溅落等等科技问题。正是基于此，他的科学幻想就是科学的预言。最厉害的是这个人没有环游过地球，他的大半生是在图书馆渡过的。

哎呀，很多人看到这边会说了：这个你就不要说了，科学家，不是文学家。

哈哈，你们又错了。科学是他的“业余”，他的主业是伟大的“文学家”、伟大的“音乐家”。“凡音之起，由人心生也”。在他十五岁那年，他爱上了几何学和康德哲学。因为欧几里得几何的清晰性和可靠性使他激动不已。此外，当他谈完了《纯粹理性批判》，康德又成了他最喜爱的哲学家。如果他的文学功底不好，试想一下，当他到达美国时，在他之前已经有很多人向罗斯福解释过：德国正在发展原子弹，如果一旦德国掌握了原子弹，那么对人类来说是一个灾难”，但是对于原子弹的解说陷于太深奥、学术，美国国会和总统无法接受。于是当时罗斯福只能摆摆手：下次再谈这个问题吧。于是人们找到了爱因斯坦，爱因斯坦用了科幻小说一般的解释手法给罗斯福上了一下午的故事会后，罗斯福终于决定当天即启动著名的“曼哈顿计划”。

这些例子，生动说明了写作、文学、甚至是文学的旁枝“艺术”乃至哲学对技术、对科学有着多么重要的推动力。

除去敲代码你还能干什么

你可以写作！

你可以开微信推广号！

你可以做管理层！

你可以做顾问！

最菜最菜你可以做架构师（设计能力-就是文档能力）！

最后，让我们以爱因斯坦著名的一句话来结束我们的第一篇“导论”吧。

“音乐和文学是我思维的源泉”。

看，这位大哥是“不仅有工作更有远方和诗”的最早躺平人之一呢！