It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

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]

13 comments

Alana Fernando Community Leader Jun 28, 2018

Good one @Jens Iwanenko 😊

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

@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? 

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.

Thanks, it sounds great. 

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

 

 

Cheers,

Gonchik

Like Jens Iwanenko likes this

Does this still work?

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.

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.

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

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. :(

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

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

Comment

Log in or Sign up to comment
Community showcase
Published in Confluence

Introducing Confluence Cloud and Jira Software Cloud Premium

Wherever you are in your team’s journey , our goal is to support your big ambitions. We’re a cloud-first company with the mission of unleashing the potential of every team, and to address the range ...

640 views 4 17
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you