技术开发 频道

人们讨厌你开源文档的13个原因

  6.缺少实战例子

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

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

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

$mech->follow_link( text_regex => $regex_object, n => $link_index );

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

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

$mech->follow_link( text_regex => qr/download/, n => 2 );

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

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

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

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

  在文档中使用超链接。

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

0
相关文章