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

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

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

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

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

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

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

1 对 “文档才是工程师的第一生产力”的想法;

发表评论

您的电子邮箱地址不会被公开。 必填项已用*标注

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据