Release notes guidelines

Learn how to adhere to Kustomer's standards of quality for documenting updates to your apps.

Changes to your app with each update should be documented in the form of release notes. The Kustomer app development team expects you to be able to tell users what's new or changed in each update. This should be similar to what your team already provides when developing for other platforms like the Apple App Store.

Why should I care about release notes?

Customers often postpone installing app updates if they lack confidence around what's changing, and if they aren't sure whether the update will disrupt their live businesses. Lack of clarity in the update process can result in an organization putting off installing a crucial upgrade, resulting in issues and downtime.

Consider the following scenario:

Andy's team worked to issue a critical bug fix for their Acme app that prevents users from losing data. It might be embarrassing to admit the bug occurred, so Andy decides to downplay the severity of the issue in the release notes. He publishes an update to the Acme app with the release notes listed as: "General improvements and bug fixes."

Xavier, an admin at a company that uses the Acme integration in Kustomer, sees the app update and reads the release notes. He's worried about causing downtime for his team, and when he doesn't see anything specific in the release notes that would make him prioritize installing the update sooner, he decides to schedule the update during the weekend later in the month. A few days later, a user on Xavier's team encounters the data loss bug in the old app version, and a case has to be escalated to Andy's support team.

How could this have been avoided?

You can mitigate this by using release notes to provide a thorough, transparent, and easily-understandable changelog that tells users about new features and functionality, bugs that were fixed, and any other relevant changes.

Release notes are an important avenue for your team to build trust with users. All software has bugs — and while it may be tempting to gloss over specifics, it's important to directly speak to issues that occur in your app in order to build and maintain healthy user expectations. Release notes aren't a rap sheet: they're evidence of your team's commitment to your users through the new features you implement and bugs you fix over time. Your customers benefit when you take the time to be direct and transparent about changes to your apps.

What to include

Do:

• Provide a bulleted list that details specific changes to your app.
• Write using complete sentences with proper punctuation, ending each sentence with a period.
• Proofread for proper spelling and capitalization of brands and terms (JavaScript, iCloud, WhatsApp, etc.)
• Speak transparently about issues being resolved in your updates, so readers are able to tell when a bug they reported is remedied.
• Frame the conversation around user value. View your release notes from the perspective of existing users who are deciding when to install your update, as well as new users seeing your app for the first time in our app directory:
  • Why should these audiences be interested in your latest changes?
  • How is their experience with your app made better with this update?
  • What do they need to know about the impact to their team already using the app?

Avoid:

• Don't write vague or repetitive statements, like "We are always improving our app with with fixes and updates." or "General bug fixes."
• While you're welcome to use compelling language to get users excited about new features, keep the conversation focused on specific changes and concrete value rather than nonspecific fluff. Release notes are first and foremost about educating and informing, not marketing.

Putting guidelines into practice

Here is an example of a typical release note with room for improvement.

In the following example, this release note accurately describes a change to the app, but the framing is focused on a potentially internal name for a change with vague user value. The release note can be improved by refocusing the message in terms of how the user experience benefits from this change.

In another example, we might receive release notes that look like the following:

Before

### What's New
- Changelog changes
- Missed calls are not logged as voicemails

These updates are far too nonspecific to meet our content criteria. If an admin knows the changelog is a core part of their team's workflow, they might be wary to install the update because they don't know how it impacts their live team. In addition, the missed calls change is vague and doesn't make it clear whether this change no longer logs voicemails, or if it fixes an issue where missed calls weren't being logged.

The release notes would need to be rewritten to explain both of these changes in more concrete detail.

After

### What's New
- Changelog
  - We've improved the changelog to include timestamps for all changes.
  - Visit the new section in the App Settings to customize changelog preferences.
- Bug Fixes
  - Fixed an issue where missed calls were unintentionally being logged as voicemails.

Examples

👍

Example #1:

What's New

• Calendar Widget
  • We've added a calendar view to the Insight Card that allows agents to see a customer's upcoming appointments.
• Keyboard Shortcuts
  • SuperApp now supports keyboard-based navigation and shortcuts for agents in the timeline.
  • Users on Mac and PC can create cases, find issues, and link conversations using modifier keys.
  • See our updated documentation for the full list of shortcuts.
• Bug Fixes
  • Fixed an issue that could cause text entered after a URL to be appended to the hyperlink instead of added as plain text.
  • Changes to the Loyalty attribute are now immediately displayed in the Insight Card.

👍

Example #2:

What's New

• Automatically log call activities including missed calls, voicemails, and recordings. Call transcriptions help capture every word between agent and customer.
• Ramp agents at scale with real-time agent recommendation cards that pop up based on keyword triggers.
• Recommendation cards can include frequently asked questions or troubleshooting steps, plus provide a link to their knowledge base, forum, or other resource page.
• Inbound calls create conversations and voice messages on the customer timeline, and include a URL of the recording URL of each call.

👍

Example #3:

What's New

• Bug Fixes
  • Critical hotfix for a crash that could occur when syncing with Acme Cloud over an unstable connection, which can potentially result in data loss.
  • Please install this update immediately to avoid potential data loss. If you or your team were affected by this crash, please contact Acme Support for recovery assistance.