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]

6 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 @Shreyas V. 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.

Like 1 person likes this

Thanks, it sounds great. 

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

 

 

Cheers,

Gonchik

Like 1 person likes this

Comment

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

Confluence CVEs and common questions

Two vulnerabilities have been published for Confluence Server and Data Center recently: March 20, 2019 CVE-2019-3395 / CVE-2019-3396 April 17, 2019 CVE-2019-3398 The goal of this article is...

111 views 0 10
Read article

Atlassian User Groups

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

Find a group

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

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you