Changelogs for web apps
2 min read

Changelogs for web apps

Death to "Minor bug fixes"

Problem

  • Modern users treat software as an investment, expecting you to incorporate their feedback into the development process.
  • You're working hard for your users, but they don't always know that.
  • There's no place you can point and say "this is how we changed stuff in the last couple of months."
  • You need to get at least another department to help you update users.
  • Users spend time mastering the software and bringing changes without telling the users can feel like the ground is slipping from under them.
  • Customer success & sales teams can't position themselves as product experts in front of customers / prospects.

Solution

  • Have an open space that you can own and update your users on what changed.
  • Continuously engaging your users can help with churn.
  • Remove the need to update all departments by centralising client-facing changes.

Changelog as a service

Key lessons

  • Git logs ≠ changelogs Think of it as the middle ground between a git log and a press release.
  • The ordering should be reverse chronological. Users shouldn't have to scroll to get an answer for "What's the latest update?"
  • If the users have the opportunity to update themselves, and there are breaking changes - make it very clear.
  • Keep data formats open for every region that might read it, starting from higher to lower: YYYY/MM/DD.
  • If possible, use something that makes it possible to link between sections. (for example: announcing a fix for an update and giving more context to user by linking between the two)
  • Tailor your dialogue for the users. (working on an open-source project and highly-skilled developers are interested in every change vs mom and pop shops who are interested in "how will this affect my business")
  • Help your users explore new features by linking to relevant help articles or using GIFS / short videos for walkthroughs.
  • If you're working within a team, consider taking the burden from your development team and use a tool that can be used without having to deploy code or write html.
  • If you're working in B2B you might want to opt for in-app release notes that sit behind some sort of authentication and/or is removed from search indexing.
  • Keep your changelog somewhere visible within the platform.

How do you structure an update?

From Keep a changelog:

Added for new features.
Changed for changes in existing functionality.
Deprecated for soon-to-be removed features.
Removed for now removed features.
Fixed for any bug fixes.
Security in case of vulnerabilities.

Further reading & listening