浅谈技术文档

国内互联网从业者在写文档上是比较欠缺的，尤其是工程师，甚至抵触写文档。据我看来，文档还是很重要的，尤其是企业越来越壮大，系统越来越复杂，文档的规范化和标准化就显得更重要。

不过，反过来说，企业太过臃肿也不利于发展，英特尔公司的安迪◎格鲁夫就曾为公司壮大后渐渐丧失初创时的高效和应变能力而忧虑。吴军在「硅谷之谜」中介绍的“扁平式管理”是解决这个问题的一种方法，它是介于两者之间的一种管理机制。这超出了本文的范围，感兴趣的朋友可以阅读「硅谷之谜」。

回到主题，由于笔者是重度强迫症患者，就助养了「看到糟糕文档就忍不住要骂人」的毛病。但也确实发现一些不好的现象和问题，比如，有时候负责需求的业务人员不了解需求或没有深入的理解，需求文档中甚至有歧义。而程序不能有二义性，等细化需求时，他一脸懵逼的表情，让人很无奈，也很无语，很……

上面的问题，应该跟国内职位分的很细有关：从战略规划，到产品经理，需求分析师，产品设计师，用户体验设计师，系统架构师，到实施者——工程师。如果继续细分，还能分更多，而层级越多，效率就越低，出错也越多。这就需要每个角色在侧重本职工作的同时对其他角色的工作有所了解，至少要知道如何衔接上下过渡部分。如果不能做好这个“偏科”，势必会导致系统在实施过程出现“断层”，或“所得非所想”，结果是「城门失火，殃及池鱼」。

听闻硅谷的工程师大多能够从上到下，掌控每一层环节，无所不通，所以他们的文化是工程师文化，那里的工程师是真正的主人。硅谷的互联网公司的产品经理很少，架构师也很少，工程师“包办”一切。也许这就是为什么国内的程序员被称为“码农”，只会码代码，可不就是码农？

另外一个糟糕问题是，业务人员常常把从客户拿来的原始需求直接放进文档，零零散散，懒得整理，更别说梳理了。为什么不整理，他们不愿意去做这个工作吗？我觉得也未必，我更愿意认为是他们「不会」，他们缺乏足够的信息处理能力。无论在哪行哪业，沟通和写作都是很重要的基本工作能力，是信息处理的基础，尤其是互联网行业。所以，写作能力的重要性可想而知。

其实，平时胡乱写些什么，都可以锻炼写作能力，当能够把一件事情向别人描述清楚时，自己才算真正理解。在写设计文档时深有体会，接到需求时可能云里雾里，但写着写着，思路就像泉涌一样越来越清晰，开发实现也自然水到渠成。

关于写文档，一位硅谷的女神曾说过：“好的技术文档都不是写出来的，而是一遍一遍改出来的。”

At 2017.02.15