Internal product announcements

Decision

We decided that each team should add a fixed step to their workflows so that the announcements are not missed. How to implement it is up to the team itself, but there is a first suggestion provided:

  • Adding a text field Announcement text to our bug fix and story/task issue types.
  • In addition, we can have a label product-announcement-aligned to indicate that the team created the announcement and aligned on the content.
  • This way a transition to IN PROGRESS or REVIEW can be blocked when this label is not added.
  • A Jira automation can be used to add the label automatically when the Announcement text field is filled inside the task.

Not having an additional column reduces the risk of dropping a task, although it should be the highest focus to bring it to production.

We announce changes in #product-release-announcements slack channel in a unified way using the following template:

Release <DATE> (<EVENING | MORNING>) - Overview

<Name of feature 1>

<Description of feature 1> <List of customers that will have access to feature 1 immediately>

...

<Attached: Screenshots>

Since the template contains also a list of users having access to a feature, it also can be used for communicating changes which are hidden behind a feature flag.

Problems

Without internal product announcements other departments won't get informed when new features or bugfixes are released. If not communicated directly to them, they have to wait for the next demo to see the changes. This might lead to situations where they are surprised by the changes, might use them incorrectly or might not be able to support our customers when they ask about these changes. Furthermore, it is likely to miss writing such an announcement when it is not a fixed step in our workflows.

Another problem is the format of the announcements. Since we have multiple product teams we should have a unified way to communicate changes.

Since we are using feature flags we need to define a process how and when to communicate releases which are not rolled out entirely yet.

Context

We already tried to announce changes in slack #product-main channel but usually a description was not added at all or it didn't contain information which describes the changes in a way that is understandable also to non-tech persons.

There is no template or workflow set up which can be used to communicate our changes in a unified way across the product teams.

Options

The following options were considered

  1. Announcing changes in the #product-release-announcements channel whenever a ticket is released
  2. Adding a column to the Jira workflow to announce changes in the #product-release-announcements channel
  3. Using commit conventions to auto generate release notes

Reasoning

Why no auto-generated release notes by using commit conventions

The recommended way of committing frequently might introduce changelog entries which are not relevant for other departments. Following a commit convention for just one commit of a PR or applying auto-generated release notes for example on pull request level might solve this issue. Nevertheless, this kind of release notes tend to be quite technical instead of focussing on the product part of a feature. Also, we recognized that adding screenshots to the product announcements is really helpful. This is why we recommend using a different approach for communicating our changes internally.

How do we ensure that the internal stakeholders are informed about product changes?

We use our #product-release-announcements slack channel for announcing our product changes. Each optilyz employee has access to this channel, and it can be used to read these announcements almost in a "git history" fashion without clutter.

How to ensure that we don't miss a product announcement?

When having a fixed workflow in Jira, we need to take an explicit decision to skip the product announcement. In all the other cases we ensure that it is sent out before doing the release. As a first approach the following workflow is suggested:

  • Add a field Announcement text to Jira tasks which needs to be filled before moving a task to REVIEW
  • Before transitioning to waiting for release we send the announcement via slack to ensure it is done prior to the release

Ensure that a feature is adding value to any stakeholder

When writing down a product announcement before starting with the implementation we might recognize tickets which do not add value to any stakeholder. When running into this situation it would be hard to write a human understandable announcement.

How to communicate changes which are behind a feature flag for some customers?

Whenever a feature is not rolled out to all of our customers, we should explicitly mention it in the feature announcement. This way other departments (in particular customer success) are aware of it when talking to their customers. After releasing the feature globally another announcement should be created.

Consequences

How do we implement this change?

Each team ensures that there is a fixed step in their Jira workflow for writing and sharing the internal product announcements for their features. They should use the provided template to write the announcements so that the format is unified across all the teams.

Jira workflow

Our workflow can support us to ensure we write announcement texts before releasing an issue: For example by adding a text field Announcement text to our bug fix and story/task issue types. In addition, we can have a label product-announcement-aligned to indicate that the team created the announcement and aligned on the content. This way a transition to IN PROGRESS or REVIEW can be blocked when this label is not added.

A Jira automation can be used to add the label automatically when the Announcement text field is filled inside the task.

Announcement template

This template should be used to write the product announcements. It starts with a title containing the release date (and time) to make it clear when the features will be available.

We try to keep each feature within one section similar to how we could structure a blog post. The section title should make it clear what this feature is about so that people can see with one view if they want to read more about it or skip to the next feature directly. For those who want to have further information a short text describing the feature and possibly linking to attached screenshots should be added.

Release <DATE> (<EVENING | MORNING>) - Overview

<Name of feature 1>

<Description of feature 1> <List of customers that will have access to feature 1 immediately>

...

<Attached: Screenshots>

Who will implement the change?

The Collect team will setup a workflow in Jira and share their template as well as learnings afterwards in the next cross-team retro.

How do we teach this change?

For applying the workflow in other teams, they can schedule a session with Philip to go through the Jira setup. Whenever one team changes something regarding this workflow, this should be communicated at the following cross-team retro latest so that we can keep the workflow in sync across teams.

What could go wrong?

It requires a little effort and time to write the product announcements properly but the value it adds should compensate.

In case an already announced release fails or need to be postponed, we should communicate in the same channel about the delay.

We could forget to add announcements, especially when there is no related ticket because we just change the feature flag.

What do we do if something goes wrong?

Since it is just communication mechanism to our internal stakeholders we can adapt it whenever we recognize space for improvement.

What is still unclear?

With this ADR, we do not specify how to communicate changes externally to our customers. This needs to be addressed in a separate ADR since it might require a different approach.

Related ADRs