Two Release Notes per Release: One for Users, One for Future Me

Two distinct release notes are created for each release: one for users and one for the future self. A user typically inquires about changes, while a month later, the individual asks why a specific change was made. A single document fails to address both inquiries without becoming excessively long. To address this issue, two concise notes are written per release.

The user-facing note adheres to three lines and focuses on the new behavior or the elimination of previous tasks. It avoids internal names, library versions, or mention of refactors. Changes without observable effects are excluded. The second note records the decision-making process, rather than the diff, which is already available in Git.

It does not include the rejected options. The private note includes three bullets: the issue being fixed, the initial attempt, and the reason for abandoning it, as well as the circumstances that may lead to revisiting the decision. Writing these notes before the deployment ensures that the benefits can be clearly communicated. Writing the user note first reveals changes that are not yet complete or that involve unrelated components.

Identifying these issues prior to deployment is more cost-effective than addressing them after the release. The user note is placed in locations where users usually search, while the private note is stored alongside the code in a plain file specific to each release. Keeping them separate prevents confusion about which note should be addressed to which audience.

This practice replaced a single changelog that was abandoned due to the difficulty of maintaining consistent content for two different audiences. Writing two shorter notes, each catering to a single reader, proved to be a more manageable approach.