如何写文档

文档的反复是很正常的。不仅如此，不得不承认写文档和看文档是一件非常让人反感的事情，但是这件事情的重要性甚至超过了算法的研究本身，希望大家能够引起重视。在大型的项目管理体系中，文档的工作要占到70％的时间。当然，多数情况下我们开发的文档只是文档体系中的一小部分。

开发人员在写文档的时候往往会略去一些自己认为“顺利成章”的事情，而这些事情中的很多往往会令看文档的人感到困惑，这是一切文档工作失误的根本原因。所以，要掌握“从读者的角度”去写文档的方法。我始终认为，文档的格式虽然重要，但是把事情本身说清楚才是文档的目的，所以目前不对文档的格式做具体的要求。但是基本的几件事情要作为文档开发过程中的基本原则提出：

1）参考文献：应该尽可能多地，不遗漏地给出参考文献，但这并不等于参考文献中论述过的内容就可以在文档中省略。一般地，我们的原则是，对于参考文献提到的部分给出简明但是完整（二者相较，完整更为重要）的论述，然后在后附上参考文献。更进一步，参考文献应当打包附在文档的载体上，因为往往查找这些参考文献有时是很困难的。

2）图表和公式：图和公式作为“把事情 本身说清楚”的重要手段，应当大限度地为这个目的而服务，所以，和这个目的无关的东西应当尽可能地去掉，从而使读者可以一目了然。对图来说，应当为其目的专门绘制，而不是随便抓来一副包罗万象的图。对公式来说，应当针对要说明的内容的特点给出关键的公式，大段的公式推导应当作为附录。所有的绘图好能够 把绘图的原始文件打包附在文档的载体上，以便后来人进行修改。（Visio绘制的图在Word里可以直接编辑，但是往往就会出问题，所以也要附上原图）。

3） 文档的论述顺序：把所有的事情都说清楚，只是文档的第一步。更为重要的目的是让读者能够通过这份文档了解设计。为了方便读者，一个很重要的原则就是让读者可以“顺序”地阅读文档。读者在阅读文档的时候，很反感的一件事情就是要把文档前前后后翻来翻去。我们应当从文档的段落安排和论述风格上做到这一点，如果有需要读者“前前后后翻来翻去”的地方，一定要用醒目的方式注明。这一点不仅在文档的撰写工作中是重要的，甚至在程序的书写中也是重要的。

4） 写文档所采用的语言：应当首先采用自己熟悉的语言，然后相应地翻译为英文。在文档工作的实践中发现，如果一上来就采用自己不熟悉的语言，文档的开发人员往往会自觉或不自觉地“遗漏”掉一些论述起来比较复杂的内容。而审查文档的人也几乎不会针对于这些提出异议。这是非常危险的，为项目日后的维护和升级埋下了失败的种子。这个问题上，我们宁可丧失时间，也不愿意丧失一篇完整并且准确的文档。