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.

Release note example showing four of almost 20 fields that can be used, depending what needs to be communicated about a release.
Figure 1: Release notes have a variety of specific fields with clear instructions for content designers and links to more information (obscured for security purposes). Shown are four of almost 20 fields that can be used, depending what needs to be communicated about a release.

 

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.

Related: The Challenges of Moving to Decoupled Omnichannel Content at Hilton

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.”

Jira displays a list of release notes in the "in-product help" panel.
Figure 2: Jira displays a list of release notes in the “in-product help” panel.

 

Users who click on an item in the list of release notes will see more information.
Figure 3: Users who click on an item in the list of release notes will see more information.

 

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.

Related: How to Develop a Content Taxonomy  

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. 

The Author

John Collins is a senior content architect on the Content Platform team at Atlassian. Long ago, John was an award-winning community journalist, but he made the move to the software industry more than a decade ago and has extensive experience with technical writing, UX writing, content strategy, content design, and localization. He has spoken internationally, but John is still learning and exploring content, design, and how best to get users the content they need.

Last Updated: November 22, 2022

This article is about

Comments

COMMENT GUIDELINES

We invite you to share your perspective in a constructive way. To comment, please sign in or register. Our moderating team will review all comments and may edit them for clarity. Our team also may delete comments that are off-topic or disrespectful. All postings become the property of
Content Science Review.

Partner Whitepapers

Heretto + ContentWRX

Together, Heretto and ContentWRX offer a complete, end-to-end solution that gives you the power to control your content cycle from start to finish.

Content Strategy for Marketing

You know content is important to marketing for your business. You might have piloted content marketing and seen success. Now what? It’s time to get strategic so you can sustain and scale. This whitepaper will help you start.

Content Evaluation Made Easier

Frustrated by content evaluation? This whitepaper explains an approach and a tool, ContentWRX, to make evaluating content easier.

Writing with Feeling: A Guide to Emotive Language for More Effective Content

Content that uses emotive language performs nearly twice as well as purely factual content. Learn more in this guide from Acrolinx.

SEE ALL