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.
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
If you want to give it a shot, here's how:
- Set up the user macro (duh).
- Install the KB Survey plugin.
- 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.
- 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> </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! </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]
Was this helpful?
Thanks!
Jens Iwanenko
20 comments