User Comments in Online Documentation

Posted by
Anastasia in Technical Writing on 2/10/20164 min read

Receiving feedback is crucial for all companies. This is the best way of finding out what route you should take in your product development, which help topics are poorely written, or what questions remain open after reading a user manual.

How do I Get User Feedback?

Product documentation is a perfect platform for getting feedback or building a community around your content. All the topics are already structured logically in the Table of Contents, people know where they are, so they are ready to provide feedback when they have it - just ask.

There are many ways to get reader feedback, and we have seens them all across different online resources:

  • Topic Voting. This is a technique when you put the rating block in each topic, and your readers will click the rating link to vote. This may be a 1-5 scale, or the binary Helpul / Not Helpful choice, or something more creative.
  • Send Feedback Link. In this case, you put the that link somehwere in your topic (typically in the header or footer). When a reader clicks that link, they can either see a feedback dialog they can use to provide some comments, or an e-mail is automatically created with the To and Subject lines filled in.
  • User Forum. This is another way to give your readers a place to send their feedback to. You can create a special Documentation section in your Forum to keep all documentation feedback in one place. Some companies add the Discuss This Topic link to each topic - it brings you into the documentation forum, which is a nice solution.
  • Topic Comments. This approach is a combination of the previous two - the feedback form and a user forum. With this approach, you add a discussion area to each topic, so readers can discuss the topic content with each other in the context of the topic, without leaving it.

The topic comments is a very good solution, and you should defenitely try it with your own online documentation. You don't even need to implement any commenting functionality yourself - there are ready solutions you can use for free. You just embed a small HTML snippet into your page. One of the most well-known commenting services is Disqus.

Using Disqus for Topic Comments

Disqus is a nice service for web site and blog owners who would like to add commenting to their online resources. You can also use this servcie for topic-based online documentation.

The idea is very simple - you sign up for a free Disqus account (this is enough), then you add your web resource into your Disqus account through its admin interface. In the same interface, you will get ready HTML code snippet to insert into your web page HTML code right before the closing Body tag. That's it - this is all you need to do!

When settings thing up in Disqus, you can enable moderation to make sure user comments are approved before they appear, and you can specify a dozen of other parameters. Every time someone posts a comment, you will receive an e-mail notification so you can go and answer your client in the page comments, or contact the client directly over e-mail.

Topic Comments in ClickHelp

In ClickHelp, you can enable commenting in a few minutes - you don't have to write any HTML code, since ClickHelp provides built-in Disqus integration. Once you sign up for a free Disqus account and get your Disqus "shortname", just go to your documentation portal settings, enable commenting and specify the "shortname". And you are done - your readers can now leave feedback for all published topics!

If the instruction above looks too short and general, check this topic in our documenation to get more detailed steps: Enable Commenting in ClickHelp with Disqus.

Team Review with Topic Comments

Let’s assume that you have enabled commenting. Getting user feedback is great, but we have yet one more awesome use case for you - your team can discuss documentation just before it becomes publicly available. This is the same exact Disqus integration, same commenting block, but with conjunction with the Restricted Access functionality of ClickHelp.

For of all, you’ll need to create a Restricted Publication.

Creating a Restricted Publication

Grant access only to your Documentation Team members (or whoever is going to review your documentation) by configuring the Power Readers list.

Adding Power Readers to Publication

This proves to be a great way to beta-test your final result, get internal feedback, and improve the manuals before they go live. The image below displays an example of such collaboration inside your team:

Team Collaboration

As you can see, ClickHelp offers you even more team collaboration options to get your documentation right just before its release. And, returning to using comments after the release - remember that your users are the people who work with your product regularly, thus, they really know your product inside out, and they will always have some ideas to share. The best practice here is to broaden this communication channel. Let the audience speak, let them feel that they matter, you’ll be amazed at the results.

To easily add Topic Comments to your own content, sign up for a free ClickHelp trial and enable Disqus in your trial portal, it's really easy. Let us know what you think in the post comments below ;)

Don't want to miss the next post? Subscribe to our Blog RSS!

Happy Technical Writing!
ClickHelp Team


Give it a Try!

Sign up for a 14-day free trial!
Start Free Trial
Post Categories
Want to become a better professional?
Get monthly digest on technical writing, UX and web design, overviews of useful free resources and much more.

Mind if we email you once a month?

Professionals never stop learning. Join thousands of experts subscribed to our blog to get tips, ideas and stories from us once per month.
Learn more on ClickHelp
By using this site, you agree to our Privacy Policy and Terms of Use.

Learn more