关于如何把技术文档写清楚的几点总结

如果想把一份技术文档写清楚，我认为总体上需要把握如下几点：

1、弄清概念。

　　把文档中所涉及的概念要弄清楚其内涵和外延。我喜欢使用定义一个数学上的集合的思维方式来在文档中描述一个概念。只有将一个概念清晰地介绍给读者，才能避免在后面的叙述中产生歧义。

2、建立术语表，使用统一的词汇。

　　最好在文档中建立一个术语表，将文档中所涉及到的重要词汇归纳并解释。更重要的，是要在整篇文档中严格地使用这些词汇，而不要随便引入新的词汇。

3、少用文字描述，多用图形、表格、列表的形式来表述。

　　冗余的文字会隐藏关键信息，导致读者需要花费额外的精力去辨别关键信息。图形、表格、列表等形式往往是突出关键信息的，甚至是只包含有关键信息，因此对于提高阅读效率有显著的帮助。

4、慎用代词(例如“这个”、“那个”、“它”等等)。

　　代词的坏处在于：如果不谨慎使用，很容易让读者不知道这个代词所具体指代的对象，最终造成理解上的歧义甚至根本理解不能。不要怕麻烦，把要指代的对象的全称写出来，这样读者再配合词汇表，可以很容易地理解要描述的对象和要表达的含义。

5、慎用同一个词表达不同的概念。

　　建议为每个概念使用不同的长词汇，但是同时可以引入一个简称(不同概念的简称可能使用了同一个词)。仅仅在确实不引起歧义的情形下(哼，谁知道什么就是“不引起歧义的情形”呢？问上帝吧……)，可以使用简称来简化文档的编写。