Skip to main content

Best Practice: Feedback (TCS)


We value feedback, and we are pretty sure you do too! Here are the different ways you can get feedback on your site.

Why should I use feedback?

Your MindTouch site should constantly be evolving, like a living/breathing document. The best way to encourage change is by eliciting and distributing feedback. Feedback will help you:

  • Ensure the intent of the documentation is realized.
  • Prevents Documentation from becoming stale.
  • Identify gaps in the documentation.
  • Highlight areas that need to be curated.
  • Gives your customers a voice.

Types of Feedback

Contextual Comments
Comments left for authors by other authors to provide feedback on articles.
Article Quality Feedback
Comments left by members (Community & Pro) providing feedback on articles.
Page Rating
All members can rate articles (happy or sad face), both raising the documentation in search results for valid queries., while inversely lowering results for negative ratings. 

Contextual Comments

How to add Contextual Comments

When an author has created an article, they will want feedback from their peers on how to improve the article. Leveraging contextual comments, you can do just that. 


Before you solicit feedback on your documentation, make sure you are subscribed to receive notifications on the page. This will make sure you receive an email if someone leaves a comment. If you are not familiar with how to subscribe to articles, read our Page Subscription documentation


Once you are subscribed, you can share links to your documentation with your peers. They can provide feedback by editing the article and adding a comment next to the section of the article that they have feedback on. This allows them to add contextual feedback. The comments are only shown in edit mode and are not indexed by the search engine. This ensures that the feedback is only seen by the author. 


To add a comment, put your cursor in the section of the article you want to leave feedback on, click on the Style block (to the right of Headers), and select Comment:


This will show the following block where you can add your notes:

Click save and you will receive an email notification with the comment information in it. The email body will look like the following:


How to mark a contextual comment as done

Once the article creator has reviewed the comment and incorporated the feedback, they can mark the comment as done by hovering over the comment icon and clicking the X icon. This will delete the comment:

Article Quality Feedback

Community Members can provide feedback on your documentation by rating them. A community member can rate if an article was helpful or not and then provide additional feedback. If they already provided a rating, they can still provide feedback by clicking on the Leave feedback icon.


Read more about setting up page rating in your MindTouch site. 

Social Discussion

Contact Support if this is  something you want to install on your site.


Social discussion allows your pro members, community members, and even anonymous users to have a discussion about your documentation. Social discussion can be added by leveraging a commenting vendor and adding it to your MindTouch site. For this setup, we recommend using Disqus. 


Before setting this up, understand the following:

  • External commenting vendors will not honor the permissions set in MindTouch. It is best to only use social commenting on sites where all of the content is public.
  • External commenting can be configured to authenticate against SSO providers, but is not configured to authenticate with MindTouch out of the box.
  • Notifications will not be triggered in MindTouch when a comment is added, but you can subscribe to notifications through Disqus.


Setting up Disqus

To start with your setup, Contact Support and have them enable a comment template which will allow you to add Disqus to the bottom of all of your MindTouch articles. 


Once the template has been created, setup a Disqus account and get the embed code. It will look like the following:

 <div id="disqus_thread"></div>
    <script type="text/javascript">
        var disqus_shortname = 'example'; // required: replace example with your forum shortname
        /* * * DON'T EDIT BELOW THIS LINE * * */
        (function() {
            var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
            dsq.src = '//' + disqus_shortname + '';
            (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    <noscript>Please enable JavaScript to view the <a href="">comments powered by Disqus.</a></noscript>
    <a href="" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>


Take this embed code and add it to the comment template like the following where you break out the <div id="disqus_thread"></div> into a DekiScript block and put the rest in a Javascript (JEM) block. Add an additional line below the disqus_shortname which will be the following:

var disqus_identifier = {{}};

This will ensure that the conversation is associated with the Page ID as opposed to the URL. Since the URL can change, you want to make sure that that the conversation is anchored with the ID which will not change regardless of how many time you move it or rename it. 


Once you have added the code, click save and then navigate to an article. You should see the following:



From here your users can authenticate with their favorite social networks or even sign up for an account with Disqus.

  • Was this article helpful?