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. 

Feedback.png

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 jira.atlassian.com, 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. 

PermissionsBestPractices.png

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 jira.atlassian.com, 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. 

ChangePassword.png

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.

ContentByLabelMacro.png

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.

Rachel
Wordsmith for Confluence Server and Data Center.

8 comments

Sachin
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.
July 1, 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
Thomas Bowskill
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.
July 1, 2020

@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
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
July 2, 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
Rachel Robins
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
July 2, 2020

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
Fabian A. Lopez (Community Leader - Argentina, Florida, California)
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
July 9, 2020

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

Like # people like this
juergen_lackinger July 15, 2020

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

Like # people like this
Bill Sheboy
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.
July 24, 2020

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,

Bill

Fadoua
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
August 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.

Best,

Fadoua

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events