读到一篇关于文档重要性的文章: https://vadimkravcenko.com/shorts/proper-documentation/
我十分同意作者的观点, 程序员作为一个设计和开发并存的职业, 文档编写的重要性不言而喻. 一份足够详细的文档, 可以再其他方面节省出大量时间,特别是当你的影响力越来越大时, 输出一份文档总比你对每个人都解释一遍好.
文档的优点
规范
不同类型的文档通常有其相应的规范, 习惯了规范后, 阅读文档可以快速的抓住重点
清晰
文档可以借助于各式各样的图案,表格,样式, 来进行更为详细清晰的表达
更为广泛的接触
文档既可以让更多的人同时观看,也可以包容每个人的观看进度. 这非常友好
如何写文档
些文档之前你首先要确立一些原则和目标:
-
我的受众是哪些人? 不同的受众在看不同的内容时的认知是不一样的. 如果你是写给你的同事,大家已经有了一些共同的知识基础,那么在许多专业的词语上面不需要额外再做解释. 但如果除了与你同样的专业人士之外,还有入门或者完全不懂的人,你可能得事无巨细的都尽可能的描述清楚.
-
文档的类型是什么? 不同类型的文档描述需要不同的规范来描述. 当你是一些测试文档时,需要详细的描述关于环境的一切以及测试的方法和结果. 而不用太在意系统是如何设计的. 当你是在描述一个系统设计文档时, 则需要在文档中描述系统中更多的细节, 让阅读文档的人抓住你文档的重点.
-
文档应该尽可能的减少主观词语描述. 尽可能的描述的是可以确定并已经得到确定的事情. 如果确实有无法得到确定的事情, 则需要明确说明. 因为文档是需要被人认识和运用的,不确定的事情通常会是一种垃圾信息. 过多的垃圾信息会让人对文档的严谨性产生怀疑.
