Nostalgic beginnings
Growing up, keeping a diary or journal was as necessary to me as breathing air. I felt as though I had to document my life and all of the changes I was experiencing (and as a teenager, it constantly felt like the Worst Thing Ever could happen any given week).
Although Mux has no journals or diaries to capture its teenage angst years, we do have a lot of changes that happen within our products from week to week. Whether it’s adding a parameter to get more specialized information with Mux Data or updating our Ruby SDK to fix a buggy function, we’re always looking for ideas on how to improve our products, and those ideas turn into real-life changes. As such, having a tool that documents changes within our products is imperative to make those changes transparent and easily accessible for anyone who might need them.
We’re excited to announce that we’ve introduced a changelog as a way for you to keep track of changes to Mux’s products, when those changes are made, and how they might affect your user experience. The changelog captures all updates and releases to Mux products from December 1, 2021 onwards. This post will dive into our process and the considerations we took to build an informative and thoughtful changelog experience.
What makes a great changelog?
Have you ever scrolled through a feed trying to track down one post you saw in passing, before finally giving up and closing the app in frustration? Or maybe you’ve read an email with a big announcement in it, but the message was so long that you lost track of what was actually happening?
If you answered yes to any of the above, then you already understand the basics of what makes a great changelog.
In our research on what constitutes a positive and effective changelog experience, we landed on the following areas of focus:
- Discoverability: The ability to search and filter posts in the changelog will allow users to access the information they need when they need it. Searching and filtering are especially helpful for users who only use certain Mux products or who want to look at specific types of changes, such as bug fixes or deprecations.
- Easy to read: Our changelog will serve as a valuable piece of documentation and a source of truth for everyone who uses our products, whether internally or externally. It needs to be clear and concise, with minimal jargon.
- Streamlined internal process for surfacing items on the changelog: One of our company values is “bias for action.” With that in mind, we wanted our changelog to be crowdsourced, where anyone from any team in the company could feel empowered to submit an entry. This accessibility is important to ensure we’re being transparent internally as well as externally. We developed an internal process that provides assistance through reviewing and publishing, so people submitting to the changelog can make sure their entries are successfully shipped.
- Keeping users informed through subscriptions: With frequent updates, it’s important to keep users informed early and often. To that end, we’ve also made the changelog available as an RSS feed.
- Trackable: Having a changelog that records analytics and insights will allow us to build on previous changes and make sure we continue offering the best experience possible. With all the considerations above, there’s always room for improvement, and metrics will be a valuable gauge of where we can make the changelog better.
To summarize, changelogs are for people. We want to make it as easy as possible for people to contribute to the changelog, read the information, and keep track of updates as they come.
To maximize this ease of use and accessibility, we had to define what types of changes should go into the changelog and what those posts should look like. Setting those guidelines was a priority from early in the project to ensure that the scope of the changelog was understood and clearly defined across the company.
Where should our changelog live?
While hashing out the details for our changelog, one of the first questions that came up was where the changelog should live: Should we put it on our primary site, like the blog? Should we host it in our Docs site, where we put our guide and reference materials?
In the end, we decided it would make the most sense to host it in our Docs; users of our products are more likely to stop by the Docs site to seek out information, and the changelog should be integrated with those resources. The final changelog URL is docs.mux.com/changelog—an intuitive extension of our current navigation structure on the Docs site that’s easy to remember and allows for quick navigation.
To increase discoverability and access, we also considered common URLs that users might attempt when trying to navigate to the changelog. We found that the URLs “changelog.mux.com” and “mux.com/changelog” came up often in our discussions, so we’ve redirected each of those URLs to “docs.mux.com/changelog”.
We’ve also added direct access points to the changelog within our primary site—you can find them within our site header and footer under “Docs & Tools.”
What changes should we address in the changelog?
Another question we needed to answer was what changes we should include in the changelog. We anticipated the changelog would capture a variety of changes across different products, so it was important to establish uniform criteria that internal submitters could follow.
We decided that it was important to include the following:
- Major product releases, which normally encompass an update to the API, some new docs or guides, and potentially some SDK version updates
- API changes, such as modifying or deprecating parameters, queries, or endpoints
- New API and Data SDK version releases
- Any limits or rate limit–related changes, for the API or otherwise
- Pricing changes
- New docs or guides
- Bug fixes, especially for bugs that affect the user experience
There will also be changes that fall outside these categories. For those scenarios, we have created an easily discoverable and accessible internal Slack channel where people can bring their questions and get general opinions on whether their change should be included in the changelog.
What information should be in a changelog post?
When considering what changelog posts should look like, we decided to develop a Changelog Style Guide to create some basic standards around voice, writing tenses and point of view, and formatting to make sure all entries are consistent.
Having the style guide is especially useful for our internal mission of making submitting entries to the changelog as accessible as possible: anyone across the company, from product managers to community managers, can access the same set of guidelines and expectations for what a changelog entry should look like.
We’ve also included guidance on organizing entries hierarchically, from most to least important information, with an emphasis on keeping things clear and concise. Each changelog entry should briefly answer the following questions:
- What change was made?
- What product(s), software, or feature(s) does this change impact? How will this change affect the specified product(s), software, or feature(s)?
- What is the severity of this change (if applicable)?
- Are there any important dates related to this change (e.g., a deprecation date for a deprecated change)?
- Are there any actions a user can take to adapt to the change?
Changelog submitters are also encouraged to utilize links as much as possible to connect users to guides, blog posts, or docs for more in-depth context where necessary.
So log and thanks for all the changes
The changelog is an exciting update to our Docs to capture and raise awareness of changes that happen throughout our products.
We’re always looking for ways to improve the developer experience, and the changelog is a big part of our journey. It’s a valuable tool and resource for our employees and our users that increases transparency and can save hours of development time. Additionally, by highlighting our experiences and our thought process for developing Mux’s changelog, we hope we can help other companies and products looking to build something similar.
We’d love to hear about your experiences with our changelog! Let us know if you have any feedback by sending an email to changelog@mux.com. While we already have some exciting new feature additions planned for the changelog, your insight is invaluable as we shape current and future updates to create the best developer experience possible!
