工作中写文档的一些经验总结

工作中写文档的一些经验总结

在工作中，有很多时间是在写设计文档、配置说明、升级部署等文档。

有时候真的很烦写文档，但是写文档又是必不可少的重要工作内容。

如何写好文档？

我个人在工作中有一丢丢的经验总结：

一、尽可能形象化，避免抽象化

以设计文档来说，用一段文字来描述“程序的算法流程”看起来实在太枯燥无味。

应当尽可能使用图表的形式来替代原有的文字的形式。（信息是蕴含在图表、文字中的嘛，<(￣▽￣)/）

善于使用流程图、时序图、UML类图等来替代文字性的描述，用表格、饼图、柱状图等来对数据进行统计总结…

尽可能将想要表达的信息，蕴含在图表中，这样会形象很多，使得接收信息者更好地接收你的“想法”。

拿伪代码描述好吗？

好，当然好，但是是分情况的好。

若注重于细节描述，使用伪代码当然比流程图好；

若注重于流程描述，使用流程图当然比伪代码好；

简单来说，合理地、恰当地使用图表来使自己想要传达的信息具象化，使得自己的文档更“易读易懂”。

二、有轻有重，有主有次

如同写文章，一定要有主有次，有轻重缓急之分。

在写代码时，有个时刻应当考虑重构：

相似度超过一定程度的代码，在多次出现时，应有重构的可能，例如作为一个公共的函数来调用？

千篇一律的代码，一定是有重构的必要性，好的代码是有轻有重，是形态迥异的，如同散文一般。

写文档也应时刻牢记，文档是要表达你的主要意图，合理安排文章的逻辑结构，突出重点、将主要信息置前强调，将次要的信息置后，让读者一目了然，能最快，最准确地把握中心思想。

或在写一段文字描述时，用高亮、加粗、斜体等方式，将重要的信息“突显”出来。

但是应注意，千万别“处处突显”，那样失去了“突显”的本意，你可以在读书时划一两个标记标出重点，但是通篇全是标记，也就看不出重点咯。

三、写的越多越好吗？

文档内容可不是越多越好！

没有重点的一大段内容，简直如同老太太的裹脚布。

很多时候内容越多会起到相反的作用，因为内容太多，读者从你的“海量”内容中获取其目的信息就更加困难。

你要找一个信息点，是从10个信息点集中查找容易呢？还是从100个信息点集中查找容易呢？答案不言而喻。

你以为内容多点，详细点是为读者考虑，但是你恰恰为其增加了信息的获取困难度。

四、从读者的角度出发

通常如何设计API接口？你需要考虑的一点是易读性。

好的API接口应该是与其功能密切相关，使用者看到API就知道接口的功能，设计API的形式是站在使用者的角度。

写文档也类似。

文档的价值在于可读、快速、准确。

读者希望看一遍就能有个大概，那你应该琢磨：如何写，读者能印象深刻呢？例如形象描述一点？少点抽象描述？

读者有时希望快速查阅自己关心的信息，那如何能使读者减少查找时间呢？突出重点、有条有理应该会有点帮助吧？写得多真的有帮助吗？内容少一点，准确一点，突出一点或许更好呢！

未完待续。