Let’s change changelogs

Publishing a changelog is the highest value activity that you’re probably not doing. You might think that keeping a changelog is a boring chore reserved for developers. On the contrary, changelogs are a medium with the potential to transform how we all work. For those of you that already keep changelogs, I’d like to expand your concept of what they can be and do. Changelogs foster product-led growth, multiply the value of work, apply to disciplines outside of engineering, and can be more effective than OKRs in increasing accountability and transparency.

What are changelogs?

On the website, Keep a changelog, developer Olivier Lacan covers the basics:

What is a changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog?

To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Who needs a changelog?

People do. Whether consumers or developers, the end users of software are human beings who care about what’s in the software. When the software changes, people want to know why and how.

The hidden powers of external- and internal-facing changelogs

Changelogs are more than a laundry list of software changes. In the post Startups, Write Changelogs, Karri Saarinen, CEO of Linear, writes:

A changelog is a simple way to communicate your progress and culture and celebrate wins. It can be a quick way to align your team to focus on creating user value.

The sneaky power of changelogs is that they multiply the value of both your past and future work. Your external-facing changelog increases the value of your past work. Your internal-facing changelog increases the value of your future work.

External-facing changelogs improve the chance that your advancements will be noticed, leveraged, and appreciated by customers. Changelogs are the ultimate product-led growth device. Instead of creating human touch-points or peripheral content to re-engage your customers, changelogs speak to your customers through the product itself. Changelogs cultivate your customers’ understanding of where your product is today and where it’s going. Understanding feeds loyalty.

To create a great external changelog, you need a great internal changelog. When you sit down to write your customer-facing changelog, you shouldn’t have to start by asking “Wait, what did we ship last week?” — this information should already be at your fingertips in your internal changelog.

Compared to your internal changelog, your external changelog should be curated and centered around customer value. Saarinen advises:

Remember to write about things that are interesting to a human. Don’t include everything you do. Writing about database migrations is not that interesting unless it results in some performance gains or improves the user experience.

Conversely, your internal changelog should be comprehensive and tailored for an audience of your peers. While your customers don’t care about the database migration, your team will care if it led to a bug that made your site go down. And your coworkers will appreciate understanding the business reason behind changes, whether a change succeeded or failed, and what was learned in the process. Imagine if, when you started at a new company, you could read a history of what your predecessors did and why. A thoughtful internal changelog helps your team make better bets in the future.

Changelogs are not just for code changes

The terms “changelog” and “release notes” are commonly used interchangeably. I prefer the term “changelog” because of its open-ended simplicity. While “release notes” are constrained to the software release cycle, a log of changes can apply to a diverse range of activities and happenings, beyond code changes.

What types of changes belong on your changelog? Let’s expand changelogs in a few dimensions.

Changelogs can record any change made by your company.

Instead of limiting changelogs to code changes, you can include other activities like marketing campaigns, PR events, social media activity, sales deals, and strategy shifts.

Changelogs can capture changes external to your company.

To paint a full picture of a product’s evolution, the actions made by the company only tell part of the story. External events and environmental shifts belong on your changelog as well. If your company sells consumer products, “Christmas” should be an event on your changelog. The beginning of Covid likely deserves a spot since it potentially had an impact on your operations and customers. If you rely on search engine traffic, a Google algorithm change is a noteworthy event.

Changelogs can consist of words, pictures, and numbers.

Today’s changelogs are textual. Some changelogs, in addition to words, include images, gifs, or demo videos. But if the goal is to capture all forms of change, why not include quantitative measures as well? Metrics can capture changes to your product’s performance like traffic, revenue, net promoter score, page load times, customer acquisition cost, or conversion rates. And metrics can capture changes in your company’s environment, like the employment rate, consumer spending, bitcoin price, or whatever matters in your domain.

Changelogs can be factual and narrative.

Changelogs can be automatically updated with facts as they fold; e.g., “Code X was deployed to production,” “Our company Twitter account tweeted Y,” or “We had Z visitors to our website.” But it’s also valuable for changelogs to tell the story of why changes were made and what happened as a result. Your changelog can be a narrative of your hypotheses, outcomes, and learning. You can’t and shouldn’t explain every change that happens, but the more context, the better.

Changelogs multiply the value of work

So what’s the point of recording all of these types of change?

Recording a comprehensive changelog of your company’s actions, circumstances, and outcomes enables you to increase the value of work.

Value takes many forms ranging from social, monetary, technical, or aesthetic. To create value, you must create change by building something, crafting something, or expressing something. You can change bits, atoms, minds, behaviors, systems, or markets to create value. But not all changes are valuable. Many changes are virtually invisible or even harmful. When someone says they will “change the world,” it raises the question “For better or worse?”

Countless metaphors express how making changes, without a notion of value, is wasteful. See “sleep running”, “mistaking motion for progress,” and, in a software context, being a “Feature factory.”

Since work is about making valuable change, it intuitively makes sense that keeping a changelog helps optimize the change you create. Changelogs help you answer:

• Is the effort/impact ratio of your work improving?
• Which of your activities is generating value and which ones aren’t?
• Based on past results, how should you balance investments across different areas like product and marketing?
• If your Northstar metric went up or down, is it something you did or was it an external factor like seasonality, Covid, or a Google algorithm change?

Without accounting for the value of previous work, perception of success is more influenced by politics and bias than actual outcomes.

Changelogs eat OKRs

When leaders look to improve alignment, accountability, and transparency in their organization, they look to frameworks like objectives and key results (OKRs). Folks should look to changelogs instead.

OKRs are valuable, but they’re cumbersome to maintain, laden with fantasy, and often contrived.

Imagine if, instead of interrupting work on a regular basis to write OKRs, everyone at your company shared a changelog. When you meet a coworker for the first time, you could read the history of what they’ve been working on and accomplished. It would give you a deep sense of how they operate and what matters to them.

Furthermore, if everyone had a changelog, it would transform how managers judge employee performance. Changelogs make it utterly clear what each person produces and the value that they created.

Changelogs facilitate bottom-up innovation by allowing managers to stay on the cutting edge of what their team is learning.

Of course, changelogs are not a replacement for goals. It’s necessary to periodically take a step back to consider what you’re trying to accomplish. But each of your goals or initiatives should have a changelog. It’s the only way to objectively evaluate progress.

Introducing DoubleLoop-powered changelogs

At DoubleLoop, we’re building a system for creating external- and internal-facing changelogs. Here’s what makes our solution unique:

1. Create your internal changelog automatically by integrating your building tools like GitHub, Jira, or Clubhouse.
2. Curate which items appears on your external-facing changelog and add context.
3. Add metrics to show and understand your impact.

Want to see an example? Check out our external-facing changelog!