Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

How we use your feedback to improve our documentation

Hello community, 

I'm Rachel, a content designer (also known as a technical writer) on the Confluence Server and Data Center team. I know many of you have appreciated the recent product roadmap updates from our Product Managers, and thought you might like to learn about how we writers use your feedback to continuously improve our documentation. 

Where does your feedback go?

There are two ways you can give us feedback on our documentation:

  • was this helpful (up vote / down vote) to indicate whether the page helped you
  • free text feedback (via a Jira issue collector) where you can describe a specific problem or suggest an improvement. 


Because the Jira project we use for documentation feedback is not public, unfortunately you don't see when these issues are actioned and resolved. We've previously considered making the project public, but have to balance the risk of people inadvertently sharing sensitive information when seeking help and describing their problem (it's more common than you might think).

So while it may sometimes feel like your feedback goes into the void, we do see it, and we use it in a number of ways.

As part of the product development cycle

When we embark on a piece of work in our product, whether it's a bug fix, new feature, or improvement, one of the first things we do is take a look at the documentation. We look at what we have, how often it's viewed, the search terms you used to find it, and how helpful you've rated it. 

Then, we dive deeper into the other feedback channels available to us, in much the same way as a product manager does. We check the documentation feedback issues, look at public feature requests on, and discussion here in the community.  This tells us many things:

  • your general level of satisfaction or dissatisfaction with the feature
  • specific issues and pain points we should address (either in product, or in the documentation)
  • any known bugs or issues that we can do a better job of highlighting.

All this information helps us keep your wants and needs front of mind when we're writing for the UI, updating documentation, or creating release notes.

An example of this in action is the new permissions features in Confluence Data Center. While researching what you need to troubleshoot a permissions problem, we collected a lot of general permission related questions. Many of these either weren't directly addressed in the documentation, or required a lot of prior knowledge to join the dots. By the end of the process we had documentation for the new feature, plus a new Permissions Best Practices page, which aims to help new admins find their feet with Confluence permissions. 


When a page starts to smell

We get regular reports about the helpfulness of documentation pages, and sometimes we notice that a page has started to smell. This means it's getting more down votes than it had previously. 

When this happens, we:

  • dive into the page and look for obvious problems
  • read all the documentation feedback issues that have been raised about the page over the past few months
  • read any open bug reports and feature requests in, our public issue tracker.

From here, we can often deduce the source of the problem, and set about rectifying it. 

A great example of this is the Confluence Server and Data Center Change Your Password page.  It kept stubbornly appearing in our list of most down voted pages. But why? It's a simple page, with clear instructions and a screenshot, showing where to change your password. It was while reading through the documentation feedback issues that had been raised about the page that we found the clue we needed. The 'Password' link in your profile doesn't appear if your user account is managed in an external directory, or other Atlassian application such as Jira. Obvious once you know, but we totally missed it.

We added a "Don't see the Password option?" section to the page with some suggested next steps, and within a few weeks the page had dropped off our most down voted list altogether, and has never returned. 


During special projects

Throughout the year we kick off a handful of special projects aimed to improve our documentation. This work is often related to a theme, like improving consistency, or tied into a product initiative.  Recently we decided to give our Macro documentation in Confluence Server and Data Center a boost. 

We know from extensive customer research that macros are really powerful, and that people often learn about macros from observing other people’s pages. But what if you don’t have access to many other spaces, or your team is just getting started with macros? We wanted to provide a bit more information about the "why" of macros, as well as the "how". 

The first step was to take a baseline of views and helpfulness for every macro documentation page.  From there, we took a close look at the documentation feedback issues we'd received from you, and spotted a number of places we could improve the information we provide, and how we provide it. 

As a result of your feedback, most macro docs now feature:

  • a better introduction, with ideas on how the macro might be used by your team
  • screenshots showing the macro in action on a page
  • clear step-by-step instructions specific to each macro, replacing the generic steps we had previously
  • known issues and limitations, where these impact the usability or suitability of the macro for your team.


It's been just over a month since we published the updates to coincide with the release of Confluence 7.5. Recently we revisited the metrics we captured at the start, and have been delighted to see a massive improvement in our helpfulness score, thanks to the great feedback we’ve been able to glean from you. 

Thank you

So if there's one common thread here, it's you. Your feedback is what helps us help you and the people in your team, as they get started with Atlassian products. 

If you found this post interesting, and want to hear more from our team - from what we’re working on, to how we work on it, please let us know in the comments.

Wordsmith for Confluence Server and Data Center.


Sachin Rising Star Jul 01, 2020

Thank you for the post @Rachel Robins , I have always found Atlassian's articles very helpful. In the past I have not offered feedback to your KB articles :(. However, moving forward I would like to provide some feedback.

Like # people like this

@Rachel Robins that's really helpful, as I often create internal articles on how to use certain features of Confluence, but with the improved macros, it looks like my time can be saved by pointing to these (and I can focus a bit more on advising people on how to style the pages using Macros... which I think would be a really interesting concept to see Atlassian do a few cookbooks!).

As a side-note: stylistically, I find Panels help me so much with documentation, especially step-by-step guides (although our Confluence server is a lot less narrow than these Atlassian pages). I then create the internal cookbooks for common request e.g. this is a section of one of my pages where it covers uploading files, then formatting and aligning them within the page; often these piece together several macros and how-tos into one page (which I find removes the barrier for some people not wanting to click off to several pages).

Annotation 2020-07-02 073328.png

Like # people like this
Matt Reiner _K15t_ Marketplace Partner Jul 02, 2020

Hi Rachel, thanks so much for this article. It's really insightful, and I'm motivated to give more feedback now. :)

Keep spreading the knowledge!

Like # people like this

Thanks for sharing your tiled layout @Thomas Bowskill , yes our theme is a bit too narrow for that, but I like the way you've used the panels to visually define each step.    And I hope as our documentation improves, you need to create less guides of your own. 

Thanks @Sachin  and @Matt Reiner _K15t_  look forward to improving our docs with your feedback :) 

Like # people like this

Thanks a lot for this article! Good timing and content!

Like # people like this

The moment I find answers to my Confluence questions on youtube instead of atlassian you have a quality issue.

Like # people like this

Hi @Rachel Robins 

Thank you for this information!  I wondered about something you note at the beginning of the post:

We've previously considered making the project public, but have to balance the risk of people inadvertently sharing sensitive information when seeking help and describing their problem (it's more common than you might think).

I believe a similar situation exists for people asking/answering questions on the community forum.  To manage the public posting, it appears that community leaders spring to action to help, reminding posters about sensitive information and removing the content.

What do you think about a similar practice for documentation feedback: making it public and having a community of leaders help out?


Thanks again, and best regards,


Fadoua Community Leader Aug 16, 2020

This is very helpful @Rachel Robins

I am trying to make our team space in Confluence the company's space "model". I will try some of the ways you described here especially the Jira Issue Collector.

I am very interested to learn more from your expertise.




Log in or Sign up to comment

Atlassian Community Events