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 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.
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.
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.
Rachel
Wordsmith for Confluence Server and Data Center.
Was this helpful?
Thanks!
Rachel Robins
8 comments