How Atlassian Builds Trust Through Change with Structured Release Notes

As the adage says, “change is hard.”

We know this individually, but imagine being the administrator for enterprise software that thousands of colleagues depend on when something changes in that software. You’re going to bear the brunt of those users’ change aversion.

Such a change is really, really hard.

At Atlassian, we recognize this and have a cross-functional “Trusted Change” group focusing on how to make change less troublesome for users. One important change the team has made is shifting to structured release notes to make the content easier for users to find and understand. This article explains how Atlassian is making the change to structured release notes and what we are learning along the way. 

Continuous Change Is Becoming the Norm

Atlassian makes project management, collaboration, and software development tools for organizations from startups to large enterprises (think Jira, Confluence, Trello, Bitbucket, and more). 

Increasingly, the products are cloud-based, (e.g. they’re accessed through a web browser and data is stored on Atlassian-managed servers).

Companies that make cloud-based software can employ something called “continuous integration, continuous delivery,” a methodology that enables multiple teams to constantly release new features and updates.

As a result, change can happen constantly in cloud-based products built with that methodology. 

But oftentimes, continuous software change leaves users feeling left behind. Our research indicates that 50% of administrators feel they have inadequate information about product changes.

Solution: Structured Release Notes

One Trusted Change pillar is “awareness,” informing customers of changes in advance. To improve awareness, our Trusted Change group focused on release notes. Historically, release notes weren’t standardized. They were hard to discover and users couldn’t easily search or filter them.

The team’s goal became delivering release notes to the right customer at the right time in the right way.

Content designers reimagined what release notes should communicate and partnered with content engineers to create a new highly structured release note content type that’s built for reuse, self-contained, rich with metadata, and UX-agnostic.

The new content type is well-suited for omnichannel use and we deliver it through a new content platform that teams throughout Atlassian can access.

New Release Note Experiences

Initially, this new release note appeared in two main places: a long-standing blog on our documentation site and in what we call “in-product help.”

The in-product help experience is our most robust so far, but we are developing additional experiences, one for all users and one geared to administrators.

Behind the Scenes, Snapshot of the New Content Operation

It’s essential that users don’t see release notes for features that they can’t access yet. To make sure this doesn’t happen, we tie the release note entries into the systems that manage user groups and the feature releases. 

When an Atlassian product team kicks off feature work, they create a Jira issue—of course!—for the feature update or new feature. That issue sends information into the content management system where release notes content lives.

Our content designers get notified to write the release note. They publish the release note in the content management system, and other systems govern when the release note is presented to users.

The Results

We defined three key performance indicators for this work:

• Engagement (from views and number of requests to the content platform for release notes)
• Volume (of published release notes)
• Sentiment (through user feedback)

Early numbers show a 300% increase in engagement with release notes. 

And, we are working toward doing a deep analysis of results in the future. We can’t share specifics about the volume of published release notes, but they are in line with our expectations. We haven’t gathered or processed user feedback yet.

Top Four Lessons Learned

No case study is complete without lessons learned, so here’s four lessons.

1. Plan for Change Management

Moving to structured, omnichannel content can be a big change for content creators. Expect to teach and coach how to write structured content.

Other stakeholders may need help understanding that changes they’re requesting have ripple effects across the same content in other experiences and to other stakeholders.

2. Unified Taxonomy Is a Must

This project connected several different systems. It’s very hard to integrate systems and relate content between those systems when each has different vocabulary.

3. Don’t Dilute Your Structured Content

Very soon after launch, we had content designers giving feedback about fields in the new content type, and we noticed that actual release notes showed a pattern of content that didn’t fit the intended usage of the fields.

Content designers were focused on communicating important information that their users needed through existing fields. Meanwhile, content architects worried that the meaning of those fields was being corrupted in ways that could have negative impacts on different user experiences.

When the content architects explained the negative impacts for omnichannel, stakeholders began to understand the impact. We decided to add a new field instead of cramming content in fields that didn’t make sense (pictured in Figure 1 above).

When meaning and content structure are in question, lean into the idea of omnichannel publishing to help stakeholders see the structured content journey.

4. The Content Model Will Evolve

Tying directly into the previous lesson learned is something we repeat every chance we get: Expect the content model to evolve. There’ll always be new technical or UX needs and new or shifting content patterns.

Never think the content model is static. 

Bottom Line

In the midst of continuous product change, structured content rich with metadata helps Atlassian meet users where they are—using our products—and give them relevant information that helps them navigate the changes.

In doing so, early indicators suggest we’re building trust with those users, as we see more users engaging with these more meaningful release notes.