How to write a good changelog and publish product news

You are a product manager, owner, app developer or marketing manager of a product and want to spread the word about the latest product enhancements. This article is for you: we explain how to maintain a good changelog. 

What is a changelog? 

A new feature was ideated, designed, built and shipped - now users need to know about it. A changelog does just that: a changelog is a list of product enhancements and product news. Typically sorted by availability date (latest first) each entry informs users about an enhancement. This can be new features, additional documentation, better integration, or the removal of major constraints or bugs. 

Who writes a changelog? 

Anyone with product responsibility or ownership should maintain a changelog. Typically, this is a:

  • Product owner
  • Product manager
  • Developer 

or a related role/group like

  • Product analyst
  • Marketing manager
  • Customer success 
  • Sales
  • Documentation 
  • Support

Who reads a changelog? 

A changelog is made for two types of consumers:

  1. Existing users of the product. People currently using your product can easily be engaged in new enhancements. During their daily usage they're not always searching for new features, especially in SaaS where product updates are shipped without notice to users. A changelog entry points users to new functionality, ideally the product news is embedded in-product to be noticed by users en-passent. Actively engaging users in new features is of great benefit. All the investments are paid for, all the work of building it has been done. Now it's time to foster usage of this feature to draw benefit from the investment: happier users, increased customer benefit and greater competitive positioning for your product. After all, the more benefit your customers get from the product the more likely the will keep paying for it. Active changelog communication is essential to engage existing users. 
  2. New customers, like sales leads, new deals or any other interested candidate. A changelog can activate existing sales leads when their "deal breaker" is added to the product. Product news can attract prospects from new markets and industries when appropriately published. After all, change log content increases your search engine discoverability because it can be written in non-marketing, straight forward product language. People in the information and discovery phases of their purchasing desission can be attracted by professional changelog content. 

Where is a changelog placed? 

A changelog can be placed in-product, with embedded product news or a changelog widget. This best addresses existing users. 

A changelog can also be published publicly, on a changelog page or via release notes distribution. This best addresses new customers, supporting your marketing and sales efforts. 

Ideally, changelog info multi channel, reaching existing users and new customers. 

What makes a good changelog entry? 

  • Changelog content is not marketing content. Users expect a precise description in the changelog item. They want to understand what's written. Entries do not need to be of excessive length or size, for example they can simply point to where the new feature is available and what it does. 
  • The title is short and on the spot. Especially in-product changelog/news should carry a short and crisp title. Avoid clickbait, just describe the new feature/function like you would talk to another user of the product. 
  • The description contains text that introduces the new feature to existing users. A screenshot or sketch can work wonders... whatever works best for you. 
  • Avoid bug fixes. Mention only major bug fixes, avoid them for news placed in-product. Keep a separate log for bug fixes in case this is really required for your product, usually a ticked system will be of better service for chasing bugs. 
  • Be honest, don't over-promise because it will kick back when interested users are disappointed after exploring the new feature. 
  • Focus on customer value. Tell the user what gets better and in particular how the new feature creates value. Think of money, time, savings or anything quantifiable. 
  • Provide examples. When introducing new features off the beaten path provide examples to guide your users towards adoption. Use "you can use this to...", "get better... with..." or "increase your... by..." to drive adoption of the new feature. 


Following these tips will help writing a good changelog and publishing product news that drive adoption. Like with every rule there are exceptions: of course you can to any viral marketing stunt that helps pushing new features to the public. You can run dedicated press releases and marketing campaigns. Though reliable, high quality changelog information will be appreciated by all users, existing and new. With Productific you can publish such a changelog, on dedicated pages and placed inside your product via embeddable widget