Getting Feedback For Your Documentation

Feedback. Feedback never changes. Most of the time feedback is exactly what a technical writer needs -- but doesn't get. Gathering feedback is cumbersome and getting spontaneous feedback is rare. Getting positive feedback is even rarer. So how does a technical writer even know if their content is any good?

After having set up my documentation grounds in a new workplace a couple of years ago, gathering feedback became one of my tasks. There are a couple of good plugins in the Marketplace for gathering feedback. What most of them have in common, is a price tag. "Let's take a look at how Atlassian are doing it. They're working with Confluence, too." That's the usual answer my superiors give when I ask them, how they want things done. So, let's take a look at what Atlassian are doing.

was-this-helpful_atlassian.png

As most of us know, in the official documentation on the Atlassian products there's a small section on the bottom that says "Was this helpful?" So I did what any good technical writer would do: research. At that time, it seemed that I wasn't the only content specialist that was interested in the Atlassian way of gathering feedback. I found an Atlassian Answer that asked exactly my question -- and it containend an official answer saying "sorry, no can do." The Atlassian Team answer at least let us know that they're using a customization of the Knowledge Base Survey plugin.

Fast forward 2 years later. My Confluence skills have since drastically improved and I'm writing user macros on a quarter yearly basis. I still haven't started gathering feedback. You all know how hard it is to get funds for a plugin that only serves few individuals and doesn't really produce income. In the meantime a couple of new plugins for feedback have crossed my table and again, my superior asked his question, "How do Atlassian do it?"

On a high streak of hacking together workarounds and manipulating other plugins, I decided to take a shot at Was This Helpful (WTH). The first thing you will notice is that the Knowledge Base Plugin is no longer maintained. It's a pity, but the latest version still seems to work with Confluence 6.9. For the form I decided to utilize Atlassian's great set of UI components, called AUI. What was left was finding out how the KB Survey works technically.

I must admit, the user macro below is only half-baked. After a quick test run I found the KB Survey reporting too stuffed, too unconvenient to read. That being said, the macro works fine, but it also still has a lot of "potential."

How it works

was-this-helpful_encoway.png

If you want to give it a shot, here's how:

  1. Set up the user macro (duh).
  2. Install the KB Survey plugin.
  3. Insert the user macro in a suitable spot. I wanted it to appear on every page of a space, so I placed it in the custom footer section.
  4. In the space you want to gather feedback on, set up the Survey plugin.

Now here's where it gets a little bit tricky. The KB Survey plugin comes with 1 questions pre-set up: "Was this helpful?" For my interpretation of WTH, we need 3 more questions, that have to be set up in exactly the order specified:

  • Incomprehensive
  • Imprecise
  • Irrelevant

The additional questions are currently hard-coded into the macro block. The reason is simple: There is no possibility to have a macro parameter that can take multiple values.

User Macro Code

Macro Name:

doc-feedback

Macro Title:

Feedback for Documentation

Description:

Inserts a simple feedback form utilizing the Knowledgebase Survey plugin.

Macro Body Processing:

none

Template:

## Developed by: Jens Iwanenko
## Date created: 2018/03/07

## Inserts a simple feedback form utilizing the Knowledgebase Survey plugin.
## @noparams

#set($spaceKey = $space.key)
#set($pageId = $content.getId())
<div id="enc-feedback">
#######
## This is the "Yes" button.
#######
 <span class="enc-question"><strong>Was this helpful?</strong>&nbsp;</span>
 <button class="aui-button enc-feedback-yes" value="Yes" name="${spaceKey}0" id="${spaceKey}0">Yes</button>
 <div class="aui-buttons">
#######
## This is the "No" button. It has a submenu if you want to be more precise.
#######
 <button class="aui-button enc-feedback-no aui-button-split-main" aria-controls="enc-feedback-reasons" 
 href="#enc-feedback-reasons" name="${spaceKey}0" id="${spaceKey}0" value="No">No</button>
 <button class="aui-button aui-dropdown2-trigger aui-button-split-more" 
 aria-controls="enc-feedback-reasons" href="#enc-feedback-reasons">Details</button>
 </div>
#######
## Don't forget to thank your users! No thanks, no feedback.
#######
 <span id="enc-feedback-thanks" class="hidden">Thanks for your feedback!&nbsp;</span>
#######
## The macro is Issue Collector ready. Add your Issue Collector to the respective Link.
#######
 <span id="enc-feedback-ticket" class="hidden">Can we improve something? <a class="enc-issue-collector">Create a ticket!</a></span>
#######
## This is where the additional questions are added in.
## If you want to use different questions, make sure to change the output here.
## Note: The value "Yes" indicates, that the question applies.
## Questions are sequentially numbered if you add your questions in a different sequence
## or if you add more questions, you can check the question's number in the KB Survey setup page.
#######
 <aui-dropdown-menu id="enc-feedback-reasons">
 <aui-item-checkbox interactive class="enc-feedback-incomprehensive" name="${spaceKey}1" value="Yes">Incomprehensive</aui-item-checkbox>
 <aui-item-checkbox interactive class="enc-feedback-imprecise" name="${spaceKey}2" value="Yes">Imprecise</aui-item-checkbox>
 <aui-item-checkbox interactive class="enc-feedback-irrelevant" name="${spaceKey}3" value="Yes">Irrelevant</aui-item-checkbox>
 </aui-dropdown-menu>
</div>
<style>
 #enc-feedback {
 border-top: 1px dotted #c1c6c8;
 padding-top: 10.0px;
 }
</style>
<script>
////////////////////////////////////////////////////////////////////////
// This should maybe be written with AJS and inside an init function. //
////////////////////////////////////////////////////////////////////////
 $('#enc-feedback .enc-feedback-yes, #enc-feedback .enc-feedback-no').click(function(){
 var trigger = $(this);
 var question = $(this).attr("name"); // The name tag contains the question ID
 var answer = $(this).attr("value"); // The answer is binary: Yes or No
 var action = "/plugins/kb/ajaxkb/submit.action?pageId=$pageId"; // This is the KB Survey action
 posting = jQuery.post(action, {
 questionId: question,
 value: answer});
 posting.done(function(data){
 console.log('Finished posting feedback');
 trigger.addClass('aui-button-primary');
 $('#enc-feedback-thanks').removeClass('hidden');
 if(answer == "No"){
 $('#enc-feedback-ticket').removeClass('hidden');
 console.log('Added ticket hint');
 } 
 });
 });
 $('#enc-feedback').insertAfter('#main-content'); // We want the form directly below our content. Let's move it there.
</script>

____________________________

Was this helpful? [Yes] [No]

18 comments

Alana Fernando
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
June 28, 2018

Good one @Jens Iwanenko 😊

Jens Iwanenko June 28, 2018

Thanks, @Alana Fernando, I'm doing my best. ;)

shreyas69 October 11, 2018

@Alana Fernando Nice info. But am just failing to find the latest Knowledge Base Plugin.

"The first thing you will notice is that the Knowledge Base Plugin is no longer maintained. It's a pity, but the latest version still seems to work with Confluence 6.9".

Can you please provide me the link for where I could find the latest Knowledge Base Plugin? 

Jens Iwanenko October 11, 2018

Hi @shreyas69. I had to do some digging myself, when I last looked it was still available from the marketplace. You can find the last version of the plugin in the archive:

https://marketplace.atlassian.com/archive/24440

It still works for us, but I can't guarantee functionality. You can download version 1.4.2 from the Version History at the bottom of the page.

shreyas69 October 12, 2018

Thanks @Jens Iwanenko

Like Jens Iwanenko likes this
Gonchik Tsymzhitov
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
December 3, 2018

Thanks, it sounds great. 

We will provide feedback after using your way in our systems.

 

 

Cheers,

Gonchik

Like Jens Iwanenko likes this
Nibu Thomas August 1, 2019

Does this still work?

Jens Iwanenko August 1, 2019

Hey @Nibu Thomas

Sorry, I can't confirm if it still works. We went ahead with a different approach of getting feedback. We are still using old, deprecated Atlassian plugins and they still work in Confluence Server 6.14. If you have a system for testing, go ahead and try for yourself. It's easier than it might seem from the article. If you don't have a system for testing: you really should have. Consider setting one up or have your IT set one up.

Nibu Thomas August 4, 2019

Thank you Jens for your reply.

Could you tell us more about the other approach as well - for feedback?

So I'm really new at this so please bear with my questions.

I installed the KB survey plugin. I created the user macro using the code and details above.

But the link to configure the KB survey seems broken. When I try to configure the plugin, it has a bunch of values that I'm not sure what they mean. I see 'Yes increment', 'No increment', 'boost amplifier, 'boost maximum and minimum' and there seem to be default values in each one. 

I'd like to insert this for all the pages in a space. But I'm not sure how to call the user macro into the footer. Where do I get a URL from..

Sorry for being such a noob. A more detailed instruction set would really help.

Jens Iwanenko August 5, 2019

Hi @Nibu Thomas

don't be sorry for just starting out on your amazing Confluence journey. :-)

So, you configure the KB Survey macro in the space where you want to collect feedback. Click on 'Configure Space' and then look for the Knowledge Base Survey tab. Just write the additional questions down in the Add an Additional Question field and hit enter. Watch the order of questions I wrote in the original article, the additional questions get automatically sorted alphabetically. I added Incomprehensive first and then Imprecise. You can change the questions but you would have to scan the macro code, I wrote the questions down there somewhere. You'd have to touch the code if you change the order of the questions.Standard_0367.pngAfter that, you need to add the macro. You can either add it to every page by hand, or you can add it to the footer section of your space like this. Just put {doc-feedback} (or however you called the macro) in curly brackets and save. That *should* give you the additional section on every page. I haven't tested lately, because I have removed stuff from our testing system.

Standard_0368.png

You can see the survey results on the Knowledge Base Survey tab, but I personally didn't like the reporting. To me it's kind of confusing.

The different approach we are using now is the Ratings for Confluence plugin by adaptavist. (https://marketplace.atlassian.com/apps/181/ratings-for-confluence) It's not as expressive, but it is a simple way of identifying pages with issues. I added a little macro for re-theming the stars rating to match our corporate design, but that's totally optional.

Hope I could help.

Jens

Nibu Thomas August 5, 2019

Thanks a lot for your time!

I was able to follow your instructions... but it doesn't seem to appear as a different section. So nothing appears on the pages. I have followed all your instructions. I wonder if there are any additional configurations while setting up the user macro. For example, what do I select in Categories? (I tried selecting Exernal content and when it didn't work, I selected all options :) Then there's another one at the end that says Definition of User Macro. I tried both "no macro body' and 'rendered' still nothing.

I liked the ratings for confluence plugin. The only issue for me is that it shows up only to authenticated users. While our entire site is a KB for unauthenticated users. Perhaps you have a workaround to make the plugin available to unauthenticated users as well?

Also, is there any way to allow users to type in free text as feedback for each article? I'm dumbstruck that there's no useable feedback plugin for confluence that gives us this ability. :(

Jens Iwanenko August 5, 2019

Have you tried just inserting the macro to a single page? If you set it up as described in the article, you should be able to find the makro in the makro browser by searching for "Feedback for Documentation". The correct rendering for the macro is "no macro body". Categories are only for the macro browser. The feedback macro is usually one where you tick the "only visible to administrators" checkbox, because your users aren't supposed to insert it where they want.

It's very hard troubleshooting this without having hands on. If you changed things in the macro code (like html element IDs), make sure you change them everywhere in the code. I'm not sure if the bottom section of the code not using AJS could be a problem in newer instances of Confluence. We are currently using Confluence Server 6.14.3 in our test system and it works there without issues. If you are using Chrome or Firefox, the developer tools can help finding issues with javascript related stuff. The macro output should work as far as I can tell. You could try removing or commenting out the last line in the script block, the one that says "insertAfter". That would insert the feedback block directly into the footer near your copyright notice.

You also seem to be using a Confluence theme, which we aren't. I can't say if there are any conflicts there.

I can't make the Ratings plugin appear for unauthorized users, unfortunately, if it isn't configurable that way. You could try contacting Adaptavist for help.

Jens

Nibu Thomas August 6, 2019

Hi Jens,

Yes, I'm able to insert it individually on a page. 

I've not made any changes to the code... I'm using the code exactly as you have left it.

Still not appearing on any page... i'm probably doing something else wrong.

We are on the confluence server 6.15. Not sure if that has something to do with it not working. It's also possible that it could be the theme over which we have made a lot of customization. Let me see if our architect can help. 

You have been very helpful. Thank you!

Like Jens Iwanenko likes this
Christian Müller June 15, 2020

Hi Nibu,

Sorry for bothering you, but I've seen that you were able to integrate/implement a very nice user feedback on you documentation. It would be very appreciated if you could share what you finally used as I'm trying to achieve the same and I find that yours presents really good.

Thanks for your help.

Chris

Like # people like this
Neustar Atlassian Administrators November 6, 2020

Hi Jens,

I'm looking for a feedback plugin where users have to give feedback about the content. We have below requirements to meet for this plugin. This will be used by the organization for analysis and reporting for the whole confluence site.

Here are the requirements:

  • Readers must be able to provide quick and easy feedback (Like/Dislike)
  • Readers must be able to optionally provide text comments as feedback
  • Readers should be limited to one feedback per topic (tracked against credentials).  One user can't apply 10 Likes to the same topic.
  • Readers should be able to modify / update their feedback (change a Dislike to a Like when the content has improved)
  • Admins / leads must be a able to generate reports across all Confluence spaces, showing number of Likes, Dislikes, text feedback (date of feedback? username ?).
  • Report must be in a common data format (CSV, xls) 

Can this plugin modified to meet this requirements? Is yes, could you please tell me how?

Let me know if you have questions. Appreciate your help

Thanks

Sidhartha Kumar Sharma October 11, 2022

Hi Jens,
I am trying to find a macro that lets users to like/dislike a page or share feedback similar to the user macro that you created.

However, we have a policy around using plugins in Confluence. For example, vendors must have completed the Security Self-Assessment and are eligible for the Bug Bounty Program on Atlassian plugin marketplace page. Additionally, the plugin should be compatible on cloud, data-center, and server versions of Confluence. Do you know of any such macros that fulfil this criteria?

Wrt the user macro that you developed, it is leveraging a now archived plugin (KB Survey plugin). Is there a way to tweak your code to make it work without leveraging this plugin? If yes, can you share some insights. Any feedback from you will be helpful. Thanks!

Jens Iwanenko October 11, 2022

Hi Sidhartha,

I'm afraid I haven't been using Confluence in over 2 years now. I remember that the KB Survey Plugin used to be open source, I believe it was an internal plugin of one of the Atlassian devs. At my old workplace we used to update a fork of the original code to support newer versions of Confluence. I may be confusing this with a different macro though, so don't quote me on that.

Since the user macro was actually just a pimped UI for the KB Survey plugin, it sadly does not work without that plugin.

In my original article I wrote that I ended up not using my User Macro. Instead, I just used a stars-rating plugin. I believe it was the Ratings plugin from Adaptavist. That one obviously comes with other limitations, but at least it was free. ;-)

Mayuresh Kamble March 27, 2024

Hi @Jens Iwanenko ,

We have used this user macro on several pages in our confluence server instance but now we are migrating to cloud, since user macros aren't supported in cloud this gives error at the end of the page - "com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'doc-feedback' is unknown."

If we delete this macro directly in confluence server then it gives "unknown macro" error which is visible in cloud after migration. Could you please suggest some solution how we can eliminate the error and migrate seamlessly without any issue.

Thanks,
Mayuresh

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events