文档才是工程师的第一生产力

文档是工程师的第一生产力，写好文档对工程师来说其实并不容易。光是对系统里这样那样的部分取一个合理的名字就不轻松。好多工程师并不具备良好的书面表达能力。能够写出语法正确、语句通顺、语义明确的文档应该是工程师的基本要求。优秀的文档应该通俗易懂，有生动有趣的示例，其结构组织合理便于查阅，内容深度循序渐进，能使阅读者的学习曲线尽量平滑。优秀的工程师不一定能写出优秀的文档，但是能写出优秀文档的工程师，一定是优秀的工程师。

好的文档很稀缺，无论是内部闭源项目，还是开源项目。一般来说，商业公司内部闭源项目的文档质量比不上流行的开源项目。就算是大公司的内部闭源项目，其文档有很多时候只是看起来长，但是实际上组织结构混乱，不方便阅读，更没有十分方便的搜索引擎来帮助检索信息。

成功的项目往往离不开通俗易懂的文档。让后来者在初步理解了业务需求后，很容易开始修改代码，而不必担心弄跨了整个项目。编写文档时应该假设阅读者是初学者，尽量降低理解文档所需要的背景知识。

Python的文档是我见过的开源项目里最好的文档。在python 的帮助文档里，你很容易找到各种工具/库的最佳方式。文档还很精心地把更常用的场景放在前面的示例中。

会议视频、培训视频等其他视频形式的信息目前还难以替代文档。（为什么党的领导要叫书记，而不是摄影师？）文档比视频教程更容易检索和查阅。严肃的知识使用文字来表达是最经济和常用的方式。目前的人工智能（搜索引擎、推荐联想算法等）对文字信息的处理最为成熟。目前为止，最方便人类检索和查阅的信息形式依旧是文字资料。以短视频和微信语音等新形式传播的信息现在流行，但是大部分短视频还是只能用于娱乐，用于学习和工作还是太低效了，更多的是用于广告和宣传。 深度学习等人工智能技术正快速发展，有望帮助人来查阅和检索视频信息，但是这些技术的还不能广泛应用于实际使用。

文档的主要内容形式应该是文字。文字是表达、记录信息最经济的形式。使用文字把项目的各种信息包括应用场景、注意事项、性能考量、主要流程、配置说明、架构设计等记录下来即可以组成一篇基本的文档原料。原料的进一步加工才能成为初稿。初稿经过几次修订和改版才有可能成为优秀的文档。

文档还应该包含适当的图表。