API Documentation Changes
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.
you guys worked really hard!
thank you all!
I like the jQuery API sub-team, they are useful
Thanks, @mekwall. You’re a funny viking — and a nice func.
I don’t mind seeing the API comments section go but you need to find a better solution than the current jQuery forum. It’s awful. It’s slow, hard to navigate, the search is atrocious, and you need to find more helpful moderators that reply to unanswered questions. This is paramount. I can’t remember how many threads I’ve posted and seen that fall by the wayside. I love jQuery, but so far I’ve received better answers from stackoverflow than from your own forum.
Good move. I never thought it made sense to be able to comment on the documentation, for me it made the docs feel less ‘official’.
I agree with Bill and just let me dream of a nice possible solution…
Integration of stackoverflow under every API function via stackoverflow tags [jQuery, add(), javascript]
API Q&A concept
——————
h1 function add()
p documentation lorem ipsum
p examples
ul
li a href How do that? (a href optional jsfiddle example)
li a href How do this?
/ul
——————-
This way users would get instant answers and you could sum up dozends of examples and faqs under each function in the api..
Just my two cents..
Comments never really felt right on the api to me anyway. Glad to see them go.
I personally really like how the forums are right now. I’m not experiencing any problems with it being slow, the editor is easy to use, and it is easy to find unanswered posts to reply to as a moderator. The current moderation system feels good, though it would be helpful to newcomers if we prompted them with a note after they make a post explaining the process so they aren’t left in the dark when they don’t see their post right away.
As far as searching, it is what it is. Try finding what you want in google, its the same deal. If you don’t word your search term properly, you may not get the results you want. The only change to that I would like to see would be to search for responses and topics rather than just topics. Currently there is no way for me to search my own responses or for topics i have responded to other than going through the long list in My Account.
Is there a way to get the API docs for offline viewing?
Best Regards
Can’t say I’m a fan of this move. The comments gave an opportunity to find additional discussion and help regarding a particular method. I think that’s important and you need to get that functionality back. If not via a comments stream then via some other construct. Forum doesn’t cut it.
From my experience the most successful docs+user contributions implementation & response is the PHP manual – http://www.php.net/manual/en/
Not sure whether they are doing a lot of modding, but people just seem to get what to post – useful examples + gotchas. It’s almost like you need a big “MAKE IT LIKE THE PHP MANUAL” message.
Your other problem is the speed of jQuery updates making comments obsolete- PHP is glacial in comparison. So there should be a #build dropdown when posting, and then you can grey out notes on older builds or put them to the bottom.
But I think you need to have some user contributions- Adobe, MySQL all manage to make it work, and it has helped me a lot in past. I also find the jQuery forum too slow, would rather post on StackOverflow.
Thanks for your time + hard work
+1 for “it works great for PHP.”
I’m not sure what that community’s magic sauce is but I’ve used PHP for years and often found extremely useful advice and code examples in the comments. The comments are often better than the documentation itself.
Check out the comments for a simple function like file_get_contents(): http://php.net/manual/en/function.file-get-contents.php
I’d also like to add: ok.
@Grady: yeah, the PHP documentation was one of the things that inspired us to give comments a try in the first place. They’ve done a great job with comments there.
Thank you so much for your hard work.
In the beginning i really hated writing javascript. With jquery you totally turned that arround. I absolutely love to write javascript with jquery!
Can’t you create an option to see the old comments? They have helped me a lot in the past.
On the other hand, linking the forum to the api can be a great help. This can be done by choosing the functions that are discussed in your post.
I, too, was thinking of the PHP manual when I read about the ridiculous comments. I would like to see the comments returned (I hardly contributed, but found they were often useful) but hire some moderators to weed out the garbage. They could sit in a queue and someone could go through once a week and approve some.
The PHP community is a little older though, which might be why the comments seem better.
For the most part I think it is critical for any API website to have users input. I know it’s always the first place I look for further explanation on things.
I’ve been having more problems trouble shooting as of late with jQuery mostly because these comments were removed. I actually came here to the blog to see if I could find an answer as to why they were removed.
You should try the PHP add a note process. You’ll see there is a lengthy explanation as to how to add and what to add. I am sure it doesn’t stop 100% of the off topic comments or spam. But if you email every one that has a comment removed explaining why I am sure the jQuery community as a whole will mature a little bit and start using the notes more appropriately.
Or give us the power to self moderate.
Thanks, everyone, for your input. I’ve made the old comments available to view again.
The feedback form we have in place now has already proven vastly more effective than the comments in identifying documentation issues and prompting the team to fix them, so we’re going to stick with it for a while.