2

In my project, I came across understanding that writing release notes is both helpful and necessary. However, it is not required by my management and I keep these files virtually to myself. You could say, I do it for self-organization. For each version of the internal prototyping software, I create a version number and update RELEASE file with the changes that have occurred since the last version. Release notes are classified into lists of new features, bug fixes and remaining limitations (features to be implemented in the next version). As my management does not require this document from me, I keep writing release notes in a free manner.

Now, I am not sure how to best formulate (I hope not be sent to English@SE; I am interested not in grammar features, but in experience of other developers here who do fill in release notes for customers) features that have been implemented. At the moment I use different grammar which is inconsistent between notes. I want to gather experience from other developers.

Do you formulate release notes:

  • starting with I/we (I/we have integrated/tested/updated some new feature), or
  • as unpersonalized sentences (some new feature has been integrated/tested/updated), or
  • as nouns: integration/test/update of some new feature, or
  • other?

At the moment, I mix all of these styles and by choosing one style, I want to be consistent with the industry standard.

Pavlo Dyban
  • 163
  • 8

1 Answers1

3

If I may put your question to one side for the moment, my primary beef with release notes is they often seem to be brain dumps.

The reader should be able to see at a glance what they're interested in. They shouldn't have to wade through pages and pages to see if their bug has been fixed, or if that long awaited new feature has finally been completed.

Consider breaking it up into sections:

  • New features
  • Major modifications
  • Minor changes
  • Bug fixes

To answer your question, keep release notes concise, neutral and impersonal.

Some examples:

Bad: After about 3 weeks of investigation, we finally fixed the calculations module late last night. It was down to an overflow in the AddSummaryTotals routine. It was returning a Long when it should have returned an Int.

Good: Overflow error fixed in calculations module

Bad: Changed the graph colours as Jake in marketing says they don't look good on his laptop

Good: Changed the graph colours to improve contrast

Bad: Stopped the reports printing an extra page at the end. I didn't think it was a major issue but it is fixed now!

Good: Stopped the report printing an extra page at the end

Robbie Dee
  • 9,717
  • 2
  • 23
  • 53
  • So you suggest writing impersonalized sentences like style 2 in my list. – Pavlo Dyban Jun 17 '14 at 14:28
  • That is the best approach in my experience. – Robbie Dee Jun 17 '14 at 14:32
  • @PavloDyban - Part of the advantage to being "impersonal" is keeping these items as brief as possible. Think of this as being more generic. – JeffO Jun 17 '14 at 15:44
  • I'd add to this answer that issue tracking numbers should be included whenever possible (there should be one for every non-trivial thing done). This way the users can just `Ctrl+F` for their issue number and instantly see whether it was resolved. I love the [JetBrains changelogs](https://confluence.jetbrains.com/display/IDEADEV/IntelliJ+IDEA+2016.1.3+Release+Notes). – marstato May 24 '17 at 08:46