如何写好技术文档 — 来自十多年的文档经验总结
加一些冗余的信息帮助读者理解文档内容。虽然很多工程师都讨厌冗余 极力追求简洁,但写文档和写代码不同,适当的冗余反而可以帮助读者理解,很简单,举个例子,比如写作中经常举例子,举的例子本质上就是冗余信息,生动的例子肯定是能帮助读者理解抽象内容的(我想这就是自举 吧)。 ### 结语 ### 目前看到比较好的一个现象就是大家越来越重视文档了,但和测试相比 重视的程度还不够。测试已经是工作流程中不可或缺的一部分了,而文档依旧还不是。当然这可能和文档本身的特性相关,测试很容易被自动化,也有非常多的客观指标来评估。文档却做不到,首先文档的书写需要人手动介入,而文档的质量也没有太多客观的指标评估,提升文档的数量和质量只能从文化和工作流程上去逐渐改变。 最后总结下本文几个关键点: - 随着时间的推移和组织规...阅读全文