Slashdot Mirror
The Strange Art of Writing Release Notes (ieee.org)
Reader necro81 writes: IEEE Spectrum has an amusing piece on how App Stores, and the frequent updates to those apps, have given release notes new prominence to average users. Unfortunately, most release notes are hum drum and uninformative: "bug fixes, performance improvements." That may be accurate, but isn't useful for determining if the new version is worth downloading. The article highlights counterexamples that weave humor and creativity into the narrative, even if it still just boils down to "bug fixes". For instance, when was the last time your release notes included ASCII art?
Although a bit old, TechCrunch also has a commentary on the highs and lows of App Store release notes.
What is the opinion of /. readers? How much information is appropriate in release notes? Should one make any attempts at levity, or keep it strictly to business? For those of you who actually write release notes, what guidelines do you use?
Although a bit old, TechCrunch also has a commentary on the highs and lows of App Store release notes.
What is the opinion of /. readers? How much information is appropriate in release notes? Should one make any attempts at levity, or keep it strictly to business? For those of you who actually write release notes, what guidelines do you use?
Release notes should generally be functional. Save the marketing for a new update for a press release.
This falls under "know your audience."
A style of release notes that might be functional for a typing tutor for children may not be suitable for an encryption library. That is, you have to keep in mind who your users are how they use your product. You also have to balance with how open your ecosystem is. For a completely closed source, closed process product I would expect a very verbose and detailed changelog. For an open source project, some short one or two line bullet points with links to bug tracker, mailing list, and/or commits in online VCS are more than adequate. There are lots of other issues to consider as well, including the volume of change. Even if it was just one liners the changelog for the Linux kernel or LibreOffice would be too large for a mere mortal.
If you can condense all of the changes in your update into one line ("Bug fixes, performance improvements"), then you're doing it wrong.
Every update for the Sony PS4 has said the same thing: Performance improvements. After so many "performance improvements", then my PS4 should be flying like a bat out of hell, right?
We all know that what they are really doing is making changes so you can't exploit bugs so you can make the system boot your own OS, or something. What really bugs me is when they actually *DO* make changes to the UI or social features, THEY NEVER TELL YOU!