Product Change Communication in SaaS

perfect for a 4 minute break β€’ written by Wim Mostmans

What do you do when you realize your SaaS company has grown so much that you cannot possibly keep everyone up to date about your product's feature updates and changes without wasting your time? Simple, you find an alternative way. A smart way. Read this article to find out how the developers at Ambassify solved this communication issue by creating our GitHub changelog.

Every SaaS company will sooner or later get to a stage of their growth where it becomes harder and harder to keep everyone in all departments up to date on what’s happening on a product level. 

Ambassify is no exception, which is why we tried to find the most suitable solution for the problem at hand. 

In this case, we thought it would be awesome to have something that ties into our current working method with GitHub, and that’s where our idea of a changelog came from. 

Making changes to a development process that almost feels like muscle memory is tricky, so it was essential to keep the extra work for the devs to a minimum to give this a chance of becoming a new habit.

image4

A changelog should just be a simple overview of the implemented changes with a short explanation, sometimes accompanied by a screenshot to illustrate the change.

Our solution

At Ambassify, we follow a standard GitHub workflow. We write a changelog for each issue that impacts the customer experience in the form of an issue comment. This changelog comment has the format shown below:

image3

Once an issue is resolved or closed, we automatically run a script in our changelog repository that searches all CHANGELOG prefixed comments and publishes them on a website.

Do note that we only search for changelog comments in closed issues. Doing this makes it possible for a developer to write a changelog for their issue already while their pull request is still in review or staging. 

What’s the stack? 

The changelog page is created using Jekyll, a static website generator.

We run the changelog search script in a GitHub action. There is a comprehensive arrangement of ways you can trigger this build script. We currently use a webhook from Zenhub as a trigger.

The script will look for changelog comments with a more recent date than the newest changelog found during the previous run. We create a Jekyll post for each newly-found changelog comment.

The next step is to build Jekyll with all up-to-date changelog posts in place.

This static website is then published to a GitHub page to which we have attached a custom domain name. In our case, this is changelog.ambassify.com.

We also create an RSS feed of all changes. This makes it possible to load our changelog in Slack to keep everyone in the team informed about new product changes.

image1

What about commit messages?

Commit message could also be an excellent way to create a changelog. A good example is Changehub, created by the devs at MadeWithLove.

However, it depends on the target audience using your changelog. For our use case, these changelogs should also be understandable for prospects that maybe have never seen the product before. For us, it was essential to work with images and other markups to give the reader a clear visual overview of the change.

Advantages

In our case, this simple solution resulted in a lot of saved communication time. To give you some examples:

  • Your Marketing department will stay up to date about new features in the platform that they can write and publish content about or use for targeted ads.

  • Your Customer Success team will be updated on new features and bug fixes to communicate with relevant customers.

  • Customers can get quick and immediate updates about features launched just minutes before.

  • If a prospect is waiting for a new feature to be released before signing the contract, the Sales team can immediately send a link to that specific change. 

  • You can link a specific feature in discussions with co-workers on Slack. That doesn’t seem like a big deal, but it helps get everyone on the same page during product discussions.

What’s next?

Is this the best implementation of a changelog? No, probably not. Not at all. But if we look at the saved time versus effort, this is a great solution that makes a difference.

We are working on an open-source solution for this project that would allow you to roll this out for your GitHub organization by just doing a simple repository fork. We believe that this can help many SaaS companies regardless of the product they are building.