A header image for the user commenting article.

We want your feedback!

Published: December 9th, 2013

Leave comments on your favorite docs

We recently implemented a user commenting system for our documentation, which lets you leave comments on any page on the Documentation or Reference tabs of the site. This week, we give you a bit more information about the system and recommendations for the types of comments that we're most (and least) likely to be able to help you with.

Our user commenting system uses Disqus, a popular framework for commenting on websites. When you visit a page in our docs, you can scroll to the bottom of the page to leave a comment or view comments that other readers have already left. In addition to creating a new comment by typing in the text box, you can reply to another comment or share the comment on social media. Below the comments for the current page, you can see user discussions that are happening on other pages.

Here's an example of what a comment looks like:

An example of the user commenting system.

When you leave a comment that includes a question, requests additional information, or identifies an error in the docs, one of our documentation experts will try to reply to your comment within two business days. We have moderators that regularly monitor all of the user comments across the site, so you can be sure that your feedback will be read, and acted upon if necessary. We'll do our best to acknowledge your comment and provide the information that you need. We may also direct you to our developer forum, which is a great community resource to help you with specific questions and problems.

What types of comments are beneficial?

There are a few types of comments you can leave that are especially useful and let us help you the most:

  • Errors or inaccuracies: If you notice something that's incorrect, such as a typo, copy-and-paste error, or some other inaccuracy, please let us know in a comment. For example, if the docs say that a function returns a certain set of values, but you notice that it actually returns different values, leave a comment with that information so we can correct our description. We strive to make our documentation correct in every detail, so these types of comments are particularly helpful.
  • Content gaps: It might be that a page doesn't include enough information or leaves out some key details. In these cases, leave a comment and let us know what you think should be added. We use that information to continually improve our docs.
  • Clarification requests: If you have a short, simple question about the content of the docs, feel free to ask it in a comment. If your question is longer or more detailed, or isn't specifically related to the docs on the page, it's better to post your question in one of the forums. By using the forums, you're giving other developers the opportunity to learn from your experiences, and you're also helping to create a better, more interactive developer community.

What types of comments aren't beneficial?

In contrast, some comments aren't quite as helpful:

  • Spam or offensive content: We won't reply to these types of comments, and we may delete them at our discretion.
  • Unrelated questions or comments: If a comment isn't directly related to the content on the page, we might redirect you to a more appropriate place to post, or we may remove the comment if it's particularly unrelated.
  • Long, detailed questions: As mentioned above, we encourage you to ask simple questions in user comments. However, for more detailed questions, or to get help with developing your app, we'd ask that you post on the developer forums instead.

Our commenting tool

As mentioned above, we chose Disqus as the framework for our user commenting system. Disqus offers a lot of features for commenters and moderators, and it's easy to use.

You don't need to have a Disqus account to leave comments on our docs, but if you find that you're posting a lot of comments, you might find the extra features of an account useful. If you have an account, you can see options that are related to your account, such as My Disqus, profile settings, and more.

We really value all of our developers and what you have to say, so please visit our docs and start commenting!