How to Create a Changelog with Uptime.com
A changelog is a chronological list of important changes users can reference as an application or service expands.
Logs explain what features are added, which are changed or adjusted and what those changes do. They sometimes provide explanation or instruction. Logs are useful for preparing your user base for scheduled application and website downtime, and giving your most loyal users something to look forward to.
Keeping a detailed and accurate changelog is easy to overlook, but failure to update or maintain a changelog creates some confusing situations. Users may ignore new features because they are unaware they exist, or misunderstand their use entirely. Big UI changes can be very jarring for users who have grown to expect an application to look and feel a certain way.
We’ll create a changelog to display on your website using Uptime.com, an invaluable resource that will also house automated notifications of site downtime events. Here’s how it works.
First, create a specific Check for some functionality, such as a Transaction or API Check. In this case, we can imagine we’re using an API that tracks route times for enterprise commercial shippers. Our customers want to know when new features are added, but they require absolute stability at all times to do their logistics work.
Our API Check will validate the critical steps of our application, such as vehicle or location tracking, or whether variables like the fixed destination are functioning.
Next, let’s configure a Public Status Page so our customers will be able to see this development firsthand. Click Reports>Status Pages>New Status Page. Whether we named our check in the previous step is not required, but it might help us select it in the dropdown menu on the Add Status Page screen.
Configuring the Status Page
Make sure this Status Page is public, and we recommend allowing search indexing. Someone may find this page when searching your domain with “down” or “is it working”.
Allowing a drill down (which provides access to technical/granular data about the incident) is ultimately your decision, but we can document some of the root-cause analysis in an incident description.
As a bonus, we can create a CNAME record. Users who visit your CNAME URL will redirect to this tool on Uptime.com, which is useful for branding. You can also edit the Header and Footer HTML, which allows a seamless blending of Uptime.com services within your application.
Click Save to deploy your public status page.
Creating an Incident
Today is a big day: our first change to report on!
Let’s revisit our public status page (Reports>Status Page). Next, click Actions followed by Manage Incidents to document your change.
First, select the Incident Type:
- Scheduled Maintenance
These options provide context for the description.
Creating Your Changelog
We’ll break our changelog down into four steps, and provide context for each step. A quick summation of what makes a good changelog:
- It’s human readable
- Chronologically lists notable changes
- Identifies versions by subsection
- Includes anything added, deprecated, changed, removed, fixed, or security related
Let’s dive into the anatomy of a changelog. For more information on how to write a changelog, read this post about why you should keep a changelog.
1. Define When Changes Will Occur
Our first step is to define the date and time changes will occur. We’re thoughtful developers, so we will attempt to give our users 12-24 hours notice that a change is incoming. We might use “Notification” or “Scheduled Maintenance” for this part of the changelog, given its content.
If we had found a serious bug, we could use “Identified” while we work to find a resolution.
2. Document New Features
Provide a list of the changes and don’t forget to include bugs you’ve squashed. Make sure to include special instructions, with accompanying screenshots or video, so users know what the changes look like and how they might feel.
We realize deadlines and development costs play a role in how much information you can provide, so we recommend you set a standard you can meet consistently. Exceed that standard when you can.
3. Live Update During Maintenance
Maintenance or deployment sometimes takes longer than expected. Use incident descriptions with the “Scheduled Maintenance” tag so users understand these issues are related to a problem already identified. Remember, transparency is a rare competitive edge.
4. Resolve Changes and Deploy
Report to users that Scheduled Maintenance is “Resolved”, and use the “Monitoring” option if you receive bug reports after deployment. You can use “Monitoring” or “Identified” to let users know you are aware of certain issues, then provide additional updates about the situation.
Final Thoughts and Tips
The changelog serves two purposes: as a method of generating interest from your most loyal users for new features, and informing all users that a change has taken place. Try and tie your product updates to blog posts that describe those features. New users will appreciate the insight into your tool, and long time users will be more likely to try out new functionality.
You should also create an Uptime.com Widget and connect it to your public status page. Leave it accessible at the footer, or in the margin, so users always have access to your changelog. The Widget also proudly displays your ratio of uptime so customers know you’re always there for them.
Minute-by-minute Uptime checks.
Start your 21-day free trial with no credit card required at Uptime.com.