When we added comments to the API documentation last January, the idea was to provide a place for members of the community to augment the documentation with their own tips or real-world examples. While this system worked well when it was first introduced, it has become increasingly difficult to manage the enormous amount of spam that it has attracted. We also found that many people were trying to use it as a support system, which it was not designed to do. Because of this, we’re planning to turn off comments on the API site later this week in favor of more directed feedback options:
- If you need help debugging your code or understanding how something works, or if you’re interested in helping others, head to the jQuery Forum or visit #jquery on irc.freenode.net.
- If you’ve found a bug or have an idea for an enhancement, please follow our bug reporting guidelines and submit your report directly to our bug tracker.
- If you notice an error or omission in our documentation and want to help us improve it, we’ll provide a simple contact form for you to fill out.
Once comments are disabled, members of the jQuery API subteam will scour old comments for any information that we can, with the commenter’s permission, roll into the documentation proper.
Observations and Lessons Learned
Even though we’ll be turning off the comment system, having it on the site the past year was a valuable experience. Here are just a few of the observations and lessons we noted along the way:
- When bug reports, feature requests, and calls for help were left in comments, instead of in the bug tracker and forums, they didn’t receive the attention they deserved.
- When well-meaning people replied to requests for help in the wrong channel, they inadvertently contributed to the fragmentation of the community.
- On the other hand, when people introduced and responded to topics in the appropriate channel, there was a much greater likelihood of successful resolution.
- Instructions for writing appropriate comments were often overlooked, regardless of their size, location, or wording.
- The value and accuracy of on-topic comments tends to wane over time as bug-fixes and enhancements are applied.
- Knowing how and when to “prune” comments was a particularly tough challenge. For example, after we revised the wording in an entry to address a comment thread, we felt that deleting the thread was appropriate. Yet, we also regretted not being able to properly thank the people who helped out without contributing to comment noise.
- If a plugin author plugs their project in the comments, is it spam? We didn’t have a good answer to this question, and many others like it, but that didn’t keep us from spending a lot of time stressing over the Right Way™ to handle these situations.
Thanks to the jQuery API Sub-team
Finally, I’d like to take this opportunity to thank those who have volunteered to commit their valuable time and resources to maintaining and improving the API documentation. The following people are members of the recently formed jQuery API sub-team:
- 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
Additionally, thanks to all of those in the jQuery community who have contributed with their suggestions, critiques, and encouragement.
