Why One Developer Writes Two Separate Release Notes for Every Shipped Update

A developer at Burning Tribe has adopted a practice of writing two distinct release notes for every software update instead of a single shared changelog. The first note, aimed at users, is limited to three lines and describes only observable changes in plain language, omitting internal details like library versions or refactors. The second is a private note for the developer's future self, recording what problem was being solved, what approaches were tried and discarded, and what conditions might prompt revisiting the decision. Keeping the two notes separate prevents the common pitfall of writing for mixed audiences, which the developer says caused them to quietly abandon a single changelog over time. The author argues that drafting the user-facing note first also helps catch half-finished or bundled changes before deployment, making it a lightweight quality check.