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.
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:
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.
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.”
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:
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.
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:
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.
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 firstname.lastname@example.org. 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!
No credit card to start. $20 in free credits when you're ready.
50 Beale Street, Floor 9
San Francisco, CA, 94105
34-37 Liverpool Street
Unit 4.06, 4th Floor
London, EC2M 7PP