如何写一手好文档(好代码)?

一、什么样的文档（代码）叫做“好”？

任何一篇文档，目标都是给别人看懂。

任何一段代码，首先也都是别人能看爽了才是目标。

以上述“世界观”为准，很容易得到文档（代码）好不好的结论。

以80后小时候读的连环画为例，它就是优秀文档的典范。

像连环画这样优秀的文档，主要具备以下几个特点：

1.长篇被分成小节。

2.小节中关键页有图。

3.描述言简意赅。

4.页数固定不多。

典型地，如果在写文档（代码）时，能够做到上述四点，都是优秀的。
比如：
PHP文档造福了多少PHP程序员，让PHP这门语言流芳百世、追随者众多。在PHP文档中，每一小节都进行了特别归类; 在关键位置还有不少例子代码; 每个方法的作用也是言简意赅; 每一小节的数量都不是很多。

再来看nginx代码，完全是一个大型服务端软件构建的一个范例。只看src目录中的源码，从一开始就分成了core、event、http、mail、misc、os，这样相当清晰明了的层级结构和定义，让后续很多事情方便扩展; 每一部分的代码都能够让读者一眼看明白是做什么的; 每个细节的方法长度也不是特别长; 每个分类里的内容也相对是固定的，后续的改进都是在plugin上比较多。

二、几种实际的土办法提高文档（代码）能力
在上述建立好了对好文档（好代码）的世界观之后，下面再分享一些总结出来的套路，如果前面世界观没理解透，只把这里的土办法理解了，也能写出来容易读的文档（代码）。

办法一、写文档先写段落标题，写代码先建分类目录（java叫做package）。
在一切开始之前，如果无法下笔，则先想想要写代码架子都有哪些。

办法二、一级段落不要超过5个。
这纯粹是个经验值，实际超过3个的时候已经开始有些遗忘前面的了。套在代码上，不要超过5种主要功能的目录，像nginx有6个，不过os和misc基本上都是固定不改的东西，所以常动的也只有4个而已。

办法三、不要没有段落画大饼
这和办法二是相反的，因为人脑对内容的吸收是有阶梯的，越往后的内容越难记住。所以在适当的时候要歇一歇。套在代码上，就是不要搞一个大类，什么都能干。

办法四、尽可能让文档（代码）先少后多
这个办法是指，让读代码的人先看一小部分，慢慢再“勾引”读者不断地深入。

好了，上面的办法都实施之后，一手好湿就应该不远了。


转载自五四陈科学院[http://www.54chen.com]