Skip to main content
MindTouch Success Center

Best Practice: Encourage Feedback

This page applies to:MindTouch (current)

This best practice article addresses the importance of soliciting feedback from your users.
 

Why should I encourage users to leave 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


  • Editorial comments.  Comments left for authors by other authors to provide feedback on articles.
  • Article quality feedback.  Comments left by community or pro member users to provide feedback on the usefulness of articles.
  • Social discussion.  Allows users to engage with other users and build a community of learning and discovery while providing inspiration and motivation to improve content.
     

Editorial comments


How to add editorial comments

When authors have created articles, they will want feedback from their peers on how to improve those articles. Leveraging editorial comments, your authoring team can set up a peer review workflow for just that purpose. 

Before you solicit feedback on your documentation, make sure to subscribe to your pages to receive notifications on the page so that you receive an email if someone leaves an editorial comment. 

Peer review workflow

  1. Subscribe to your authored page.
  2. Send page links of your authored pages to your peers.
  3. Have peers provide feedback by adding a comment. To add a comment, users must open the page in Edit mode, navigate to the Styles menu and select Comment from the drop-down menu.


 

  1. When reviewers Save,  you will receive an email notification similar to the following:

Image of email notification of feedback

Editorial comments are only shown in edit mode and are not indexed by the search engine. 

  1. Reviewed the comment and made necessary changes.

  2. Delete the comment to indicate completion of the change.

Image of editorial comment with delete icon selected
 

Article quality feedback


Users can provide feedback on your documentation by rating whether 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 to enable social discussion 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.

How to set up Disqus

  1. Set up a Disqus account and get the embed code. It will look like the following:
< div id = "disqus_thread" > < /div> <script> 
/ * * * RECOMMENDED CONFIGURATION VARIABLES: EDIT AND UNCOMMENT THE SECTION BELOW TO INSERT DYNAMIC VALUES FROM YOUR 
PLATFORM OR CMS.*LEARN WHY DEFINING THESE VARIABLES IS IMPORTANT: 
https: //disqus.com/admin/universalcode/#configuration-variables
 */ /* var disqus_config = function () { this.page.url = PAGE_URL; // 
 Replace PAGE_URL with your page's canonical URL variable this.page.identifier = PAGE_IDENTIFIER; 
 // Replace PAGE_IDENTIFIER with your page's unique identifier variable }; 
 */ (function() { // DON'T EDIT BELOW THIS LINE var d = document, s = d.createElement('script'); 
 s.src = '//averytestsite.disqus.com/embed.js'; s.setAttribute('data-timestamp', +new Date()); 
 (d.head || d.body).appendChild(s); })(); </script> 
 <noscript>Please enable JavaScript to view the <a href=
 "https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a></noscript>        
  1. From this embed code and add the following line  to a DekiSrcipt block:

<div id="disqus_thread"></div>

  1. Add the rest of the code into  a JavaSript (JEM) block.
  2. In the Javascript (JEM), delete the comments and assign values to variables: 
this.page.url = PAGE_URL;

and 

this.page.identifier = {{page.id}}; 
  1. After the comments are removed and variables are assigned the Javascript (JEM) Block should look like this:
/* var disqus_config = function () { this.page.url = https://averyd.mindtouch.us; this.page.identifier = {{page.id}}; }; 
*/ (function() {  var d = document, s = d.createElement('script'); s.src = '//averytestsite.disqus.com/embed.js'; 
s.setAttribute('data-timestamp', +new Date()); (d.head || d.body).appendChild(s); })(); /*

This ensures 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 times you move it or rename it. )


 

  1. 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?