API 文档变更

发表于 作者

api.jquery.com 上的评论示例 当我们在去年一月为 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 社区的各位成员，他们提供了建议、批评和鼓励。

关于“API 文档变更”的 17 条评论

  4. Bill Williamson on 说：

    我不介意看到 API 评论部分消失，但你们需要找到一个比当前 jQuery 论坛更好的解决方案。它太糟糕了。它很慢，难以导航，搜索功能很差，而且需要更多有帮助的版主来回复未解答的问题。这是至关重要的。我不记得我发布了多少个帖子，却看到它们不了了之。我爱 jQuery，但到目前为止，我在 Stack Overflow 上得到的答案比在你们自己的论坛上得到的答案更好。

  5. Cam Skene on 说：

    好主意。我从未觉得在文档上进行评论有意义，对我来说，这会让文档感觉不那么“官方”。

  6. gabel on 说：

    我同意 Bill 的观点，让我梦想着一个可能的解决方案…

    通过 Stack Overflow 标签 [jQuery、add()、javascript] 将 Stack Overflow 整合到每个 API 函数下

    API 问答概念
    ——————

    h1 函数 add()

    p 文档 lorem ipsum

    p 示例

    ul

    li a href 如何做到这一点？（a href 可选 jsfiddle 示例）

    li a href 如何做到这一点？

    /ul

    ——————-

    通过这种方式，用户可以立即获得答案，你们可以在 API 中的每个函数下汇总数十个示例和常见问题解答。

    仅供参考…

  7. Kevin Boudloche on 说：

    对我来说，评论在 API 上从来没有感觉正确。很高兴看到它们消失。

    我个人非常喜欢现在的论坛。我没有遇到它运行缓慢的问题，编辑器易于使用，并且很容易找到未解答的帖子作为版主回复。当前的审核系统感觉良好，尽管如果我们在用户发布帖子后向他们发送一条说明，解释审核过程，那么对于新手来说会很有帮助，这样他们就不会在帖子没有立即显示时感到困惑。

    至于搜索，它就是它了。尝试在谷歌中找到你想要的东西，情况相同。如果你没有正确措辞搜索词，你可能无法获得想要的结果。我唯一想要看到的改变是搜索回复和主题，而不仅仅是主题。目前，我无法搜索我自己的回复或我回复过的主题，只能在“我的帐户”中浏览很长的列表。

  9. Jethro Larson on 说：

    我不能说我喜欢这种改变。评论提供了一个机会，可以找到有关特定方法的其他讨论和帮助。我认为这很重要，你们需要恢复该功能。如果不是通过评论流，而是通过其他结构。论坛达不到要求。

  10. Bodyscanner 于 说：

    根据我的经验，PHP 手册是最成功文档 + 用户贡献的实现和响应方式 - https://php.ac.cn/manual/en/

    我不确定他们是否做了很多修改，但人们似乎明白应该发布什么 - 有用的示例 + 注意事项。这就像你需要一个大的“像 PHP 手册一样”的信息。

    另一个问题是 jQuery 更新的速度使得评论变得过时 - 与之相比，PHP 就像蜗牛一样慢。因此，在发布时应该有一个 #build 下拉菜单，然后你可以将旧版本的注释灰显或放到底部。

    但我认为你需要一些用户贡献 - Adobe、MySQL 都设法让它发挥作用，并且在过去帮助了我很多。我也发现 jQuery 论坛太慢，更愿意在 StackOverflow 上发布。

    感谢你的时间和辛勤工作

  12. Karl Swedberg 于 说：

    @Grady: 是的，PHP 文档是我们最初尝试使用评论的灵感来源之一。他们在那里对评论做得很好。

  13. Michael 于 说：

    非常感谢你的辛勤工作。
    一开始我真的很讨厌写 JavaScript。有了 jQuery，你彻底改变了这一切。我非常喜欢用 jQuery 写 JavaScript！

  14. Christophe 于 说：

    你不能创建一个查看旧评论的选项吗？它们在过去帮助了我很多。

    另一方面，将论坛链接到 API 可以提供很大的帮助。可以通过选择帖子中讨论的功能来实现。

  15. Renowned Media 于 说：

    当我读到关于荒谬评论的内容时，我也想到了 PHP 手册。我希望看到评论恢复（我几乎没有贡献，但发现它们经常很有用），但聘请一些版主来筛选垃圾信息。他们可以排队，有人可以每周查看一次并批准一些。

    不过，PHP 社区历史比较悠久，这可能是评论看起来更好的原因。

  16. Murray 于 说：

    我认为，对于任何 API 网站来说，用户输入都是至关重要的。我知道这是我寻找进一步解释的第一站。

    最近，我使用 jQuery 进行故障排除时遇到了更多问题，主要是因为这些评论被删除了。我实际上是来到这里博客，想看看是否能找到关于为什么删除它们的原因。

    你应该尝试 PHP 添加笔记的过程。你会看到关于如何添加和添加什么的详细说明。我相信它不能完全阻止所有不相关的评论或垃圾信息。但如果你给每个被删除评论的人发送电子邮件解释原因，我相信 jQuery 社区整体会成熟一点，并开始更恰当地使用笔记。

    或者给我们自管理的权力。

  17. Karl Swedberg 于 说：

    感谢大家的意见。我已经重新开放了旧评论的查看权限。

    我们现在使用的反馈表格已经证明比评论更有效地识别文档问题并促使团队修复它们，因此我们将继续使用它一段时间。