去年 1 月,我们在 API 文档中添加了评论,目的是为社区成员提供一个地方,让他们用自己的提示或真实世界的例子来补充文档。虽然这个系统在刚推出时运作良好,但随着时间的推移,管理它所吸引的海量垃圾邮件变得越来越困难。我们还发现,许多人试图将其用作支持系统,而这并非它的设计初衷。因此, 我们计划在本周晚些时候关闭 API 网站上的评论,转而采用更直接的反馈选项
- 如果您需要帮助调试代码或了解某些事物的运作方式,或者您有兴趣帮助他人,请前往 jQuery 论坛 或访问 irc.freenode.net 上的 #jquery。
- 如果您发现错误或有改进建议,请按照我们的 错误报告指南 将您的报告直接提交到我们的 错误追踪器。
- 如果您在我们的文档中发现错误或遗漏,并希望帮助我们改进它,我们将提供一个简单的联系表格供您填写。
一旦评论被禁用,jQuery API 小组的成员将仔细检查旧评论,寻找任何信息,并征得评论者许可后,将其整合到文档中。
观察和经验教训
虽然我们将关闭评论系统,但过去一年在网站上启用它是一次宝贵的经历。以下是一些我们沿途观察到的观察结果和经验教训。
- 当错误报告、功能请求和求助信息留在评论中,而不是在错误追踪器和论坛中时,它们得不到应有的关注。
- 当好心人以错误的方式回复求助信息时,他们无意中助长了社区的分裂。
- 另一方面,当人们在适当的渠道中引入和回复主题时,成功解决问题的可能性要大得多。
- 编写适当评论的说明经常被忽略,无论其大小、位置或措辞。
- 随着错误修复和增强功能的应用,与主题相关的评论的价值和准确性往往会随着时间的推移而下降。
- 知道何时以及如何“修剪”评论是一个特别棘手的挑战。例如,在我们修改了条目中的措辞以解决评论线程后,我们认为删除该线程是合适的。然而,我们也后悔没有能够适当地感谢那些帮助我们的人,而不必为评论噪音做出贡献。
- 如果插件作者在评论中宣传他们的项目,这算不算垃圾邮件?我们对此问题以及其他类似问题没有好的答案,但这并没有阻止我们花费大量时间去纠结处理这些情况的正确方式™。
感谢 jQuery API 子团队
最后,我想借此机会感谢那些自愿贡献宝贵的时间和资源来维护和改进 API 文档的人。以下人员是最近成立的 jQuery API 子团队的成员。
- Adam Sontag
- Addy Osmani
- Alex Sexton
- Dan Heberden
- Dave Methvin
- Eddie Monge
- Jonathan Chaffer
- Karl Swedberg
- Paul Irish
- Richard Worth
- Rick Waldron
- Scott González
- Sean Koole
- Todd Parker
此外,感谢 jQuery 社区中所有通过建议、批评和鼓励做出贡献的人。