Startups, Write Changelogs

Changelogs are not uncommon in software development, but often they are not used in early stage companies to engage with users and investors.

We picked up the practice of writing a changelog when we started building the issue tracking and project management tool Linear. It felt natural to share updates as our goal is to build the most streamlined tool for software teams.

Our initial aim was to share the latest product changes with our early adopters and communicate how rapidly we were adding new features and fixing bugs. In the last 12 months, we have published over 50 changelogs. After doing these changelogs for a year, it turns out it was more impacful than we ever thought.

What we learned

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.

Momentum
In the early stages of startups, it’s important to keep moving and make progress. As Paul Graham says, startups rarely die in mid keystroke but they die because they get demoralized and give up. Having a changelog reminds you each week that the way forward is to keep making something people want.

Early Adopters
Most startups start with a core group of early adopters. These are people who are excited and willing take a risk of a newly developed software, and likely want to be part of helping to shape the product as well. Fixing things and publicly sharing the new changes and additions shows that you value the user feedback and want to improve the product for them.

Culture
Weekly changelogs help communicate that the company values execution and shipping things, which is crucial in startups. If you don’t ship your work, you are not creating value for users, and increase the value of the company. It can also be a celebratory moment for the team as a whole when team members release their first features and sees the user feedback in real-time.

Marketing
We have over a thousand people who follow and interact with the changelog updates. They find the progress, design, and other changes inspiring, and sometimes share it with their co-workers or friends, even if they are not Linear users. This spreads the word and leads to more people adopting Linear.

Recruiting
As the changelog is public, it acts as marketing for potential candidates: things about your culture, the product, and how you make progress. Most of our candidates have followed our changelog posts for a while before applying. Companies that execute fast, while valuing quality and craft, is appealing for many builders. Actions speak louder than words.

Investor relations
Likely the majority of angel investors and VCs that I met mentioned they have been following our changelog updates, and have been impressed by the progress. This means that even before talking to them, they already had some sense of how we work, how the product works and how fast we make progress. They also see the public response to these changes, further validating the product value to the users.

Investors often also evaluate the opportunities and risks of any given company. With early-stage companies, one of the risks is the execution, whether the founding team is the right team and able to build the product they envision before they run out of money. A changelog is a public way to demonstrate that you can execute on the plans you have.

How to write changelogs

Experiment to find your way and voice that works for your audience and product. For inspiration, you can check out our changelog at https://linear.app/changelog and see how we share the updates on Twitter: https://twitter.com/linear

Example changelog from https://linear.app/changelog

Our recommendation:

• Set up a schedule, like a weekly or bi-weekly cadence. Try not to slip. If you don’t have anything for a given week, try to understand why the progress is slow. Sometimes you just need to focus on large changes. We pair our changelogs with our cycle (sprint) progress Linear, so the changelog is kind of a summary of what we achieved in our cycle.
• 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.
• We rotate the writing responsibility within our team. Usually it’s the person who built the feature also writes the changelog.
• Feature 1–3 larger changes, and collect all the little fixes in one section. Some of those little fixes are still important and show you care about fixing small bugs and annoying things that users might encounter.
• Depending on your audience, try to figure out what is the right voice. Technical audiences likely appreciate more technical details, but others may not.
• Include one or more screenshots or videos of the features if possible. This makes it more engaging and sometimes easier to get the gist of the change, especially for people who are not familiar with your product. We include a screenshot in the post, and then share additional videos on Twitter.
• The tool doesn’t matter, the important thing is that you write the changelogs. You can write them in plain text, put them on Github, use Notion, blog, or share screenshot on Twitter. We write ours in markdown which is then rendered on our next.js based marketing website.
• We then also share this on our Twitter account with product screenshots or demos of added features.
• We also allow people to subscribe to the updates newsletter during onboarding. You can copy the content from your changelog post, and paste it to newsletter tools like Revue or Mailchimp.

Subscribe to updates on https://linear.app

So write changelogs. It’s an easy and low-effort way to keep the momentum, get new users, recruit, and build investor relationships. All things that help your company to be more successful.

If you start writing a changelog after reading this, let us know by tweeting us at @linear or @karrisaarinen.