6.缺少实战例子

　　对于基于代码的项目来说，将项目运用到实战中的一些例子和截图一样也是有益处的。这些来自真实环境中的例子不是抽象的，而不是一些几乎是一次性的充满了演示名称的例子。我们需要做的是花费些时间来做一些例子，这些例子能展现用户使用软件怎么样解决实际项目中的问题。

　　我们以前经常在数学课中使用问题解决的教学方式，这种方式能够有效的应用在我们所教的内容中。

　　以前，我写过一个web机器人模块，并且想要解释下面的_link方法，可能会像下面一样展现这个方法的定义：

　　但是，如果我通过将它运用在实际例子中，它将变的多么易懂啊!

　　#点击第二个超链接会链接到字符串"download"

　　通过这个例子，上例中抽象的占位符变量名$regex_object和$link_index在学习者的脑海中将有相同的含义。

　　当然，你的实际例子不应该像上述例子中仅有两小段。正如Apache 项目的Rich Bowen说的，“一个正确的，体现功能的，可测验的，可评价的例子将胜过一页的项目功能赘述”。

　　不管怎么说，尽你所能，空间什么的都是浮云，专门为例子制作一份专门的文档，甚至哪怕是一本书，可以从用户那儿征集实际代码，并将它们中的最好例子展现出来。

　　7. 缺少足够的链接和参考

　　在文档中使用超链接。

　　不要以为一些东西在文档里面被说明了，就认为读者已经读了那部分文档了，或者甚至以为读者知道在哪里。比如你代码中有一段涉及到操作frobbitz对象，那你就有必要在第一次使用术语 frobbitz对象的时候，解释一下什么是frobbitz对象，或者链接到说明文档的相关章节。最好是上面两个都做。