写文档的原则

序

个人认为，一篇优秀的文档是用简洁明了地阐述一件完整的事情。所以，最重要的两个原则是简洁明了和完整性。本文总结了一些相关原则和具体方法，请多多交流斧正。

完整性

故事要讲完整，有头必有尾，画一个树要完整画出其所有关键部分。最重要的文档三要素：

• 目的与背景–为啥要做，可以有啥作用。
• 方案–怎么做的。
• 结论–成果如何，是否达到目的。

尤其是最终要的结论部分。

在写作顺序上可以用，可以采用总分结构，也可以分总结构。

简洁明了

如何才是简洁明了，这个定义实在太难，太抽象，只能意会不能言传。这里拿画树来做比方讲述简洁明了。简笔画树是简洁明了的突出了树的神貌，你可以看出来树种类，叶子稀疏程度之类的。汉字树只有其抽象概念，不知道任何细节，信息太少；最后一张树的照片，太详细了，作为文档来说，文字太多了，淹死人。



如果做到简洁明了，这里总结了一些小技巧。

多用图和表

人是视觉动物，一图胜千言。

常用的图有：
gif动画图、文氏图、图论的图、流程图、思维导图、时序图等。

图表有：
柱状图、折线图、点图、3D地理图等等。

表格，就是常见的表格，最重要的是解释清楚列的含义及列与列之前的联系。

高内聚低耦合的概念

每个程序员都差不多明白，高内聚和低耦合的概念。写文档也应该如此，越相关越紧密：即相关的事物放在一起描述和展示，有规律摆放，给人整洁有序的，阅读更加清晰和轻松。
比如，目录章节，章节之间有低耦合的能力，章节内部往往联系很大。
比如，Excel表格中，相关的行放在一起，并用同样的底色，也很好的起到高内聚的作用。

多引用通识概念

引用俗语和典故来解释某个事情，容易事半功倍。

比如“三个臭皮匠顶一个诸葛亮”，“投票机制”，“折半查找”，“幸存者偏差”。

多用前人惯例

多用前人惯例，或者国际通用标准，也会让文档看起来简洁。

比如一个很大的数字5347492347很难知道到底多大，在会计通常以千位分隔符（逗号）进行分隔，即5,347,492,347，可以清晰看出来是53亿多的一个数字。

比如手机号码，加上空格更加容易阅读，134 7862 8972。

比如要用来衡量当前模型二分类的能力，那就用F1-score，AUC这些通用指标来描述。

比如要看种子质量是否高，可以看发芽率等指标。

对比鲜明

俗话说“没有比较就没有伤害”，“人比人得死，货比货得扔”，这是反例，但清晰可见对比的作用。其实表格和图片，已经暗含了对比的作用，但是在写文档之时，总有同事会忘记此事。所以，值得在此单独成章节再次强调一下。

对比的核心是放在一起进行对比我们所重视的内容，所以写文档，要把要比对的事物放在一起：

• 比如两次方法的评价指标放在一个图或表格的临近两行。
• 比如两个帅哥图图片左右排列，哪个更优秀一目了然。
• 比如两种方法对某些植物的生长状况的对比。

对比常用的表现形式是图和表，所以大家在写实验记录的表格时，一定要把对比功能作为第一要义。