The Strange Art of Writing Release Notes (ieee.org) 70
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?
Functional (Score:4)
Re:Functional (Score:5, Insightful)
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.
Re: (Score:3)
While the sudo manpages get short shrift [explainxkcd.com], the Sudo release notes [www.sudo.ws] are one of the best examples of open-source release notes.
They are
Re: (Score:3)
The trick to writing release notes is to cover up your gaffes, cock-ups and drunken coding sessions.
That bug that formats your hard drive? "Minor bug fixes."
That cat meme easter egg you tried to add in turned into a huge, show stopping bug? Better list the deleted code as a "quality enhancement."
Re:Functional (Score:5, Insightful)
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!
Re: (Score:2)
Didn't they point out the external drive support in the release notes? I had read about it before from beta releases, but I thought it was in the release notes too.
Re: (Score:2)
What I find amusing is when MS thanks you for using their office suite, like most people have a choice.
What is the opinion of /. readers? (Score:5, Funny)
Oh, wait. That's not what you were asking? Well you suck.
Sad but true (Score:3)
Though, frankly, "average" users don't read release notes.
Determining which to download? (Score:3)
That may be accurate, but isn't useful for determining if the new version is worth downloading.
Reading through release notes to see if a new version is worth downloading? Ain't nobody* got time for that!
This is the 21st century, I expect no less than that every every software component automatically and silently updates itself in an unobtrusive manner. Android, iOS and even Windows Mobile figured this out ages ago -- figure out what times of the day the user doesn't use their phone for hours at a time, wait for both power & WiFi and substantial inactivity, then go do it. Windows 10 very visibly flubbed it by missing the 'inactivity' part (oh well), but lots of projects do it well and you don't notice. Chrome is exemplary in this respect: no one every talks about Chrome updates because they just silently happen, correctly and without interrupting the user.
There is no reason that the device can't figure this out without my help.
* OK, fine, there should certainly be some setting somewhere where you can put it on full-manual mode for all updates. Why anyone would want that is totally beyond me, but here's to constructive differences.
Re: (Score:3)
>This is the 21st century, I expect no less than that every every software component automatically and silently updates itself
Oh, HELL no.
I am sick and tired of apps moving around the GUI and removing features in the name of "latest update". I'm now to the point that I refuse to update an app unless I have a good reason. That does mean that my phone has +50 pending updates - but unless they give me a good reason in the update notes, I ain't doing it.
I've had enough. I want my phone to be my phone, and
Re: (Score:3)
Sure, I said we should have allowance for the minority of folks that want full manual control. Every operating system allows this, more power to you.
Just don't complain about getting pwned when the vulnerability was patched ages ago and you never took the update.
Re: (Score:3)
First, that might be a good reason to turn off automatic updates for Java only. Not a great one because of security fixes, but OK.
Second, what happens when you have two of these programs that require specific and different versions? Or when one upgrades and the others don't. Or who knows.
Finally, I searched for "multiple concurrent java versions" and got a number of results for all OSes on how to keep them all sorted. So having a single bespoke version of Java for your one finicky program and then keeping t
Re: (Score:2)
I've been playing with Qubes OS. It lets you create VMs quickly and seamlessly, meaning you can easily run multiple copies of applications that are completely separate. It's great for running multiple versions of things, and for running untrusted software like Java in a heavily protected sandbox. The VMs are mostly transparent, the apps appear on the desktop as if they were running natively, except for some limitations on things like copy/paste and file access.
Re: (Score:2)
I've used it for years and never even heard of this.
But it was literally one Google search [google.com] to figure out how to disable it. Total time: 2 minutes from figuring how what to search for, changing the setting and then restarting Chrome.
Probably less time than I spent writing this post and checking that the link is correct.
Re: (Score:2)
A fine art (Score:3)
Release notes may not always indicate what bug fixes have actually been included. If you have an installed base you may not wish to signal an unpatched vulnerability in the field to the unscrupulous. You may also be somewhat vague about a fix that enables the product to achieve the specification which marketing claims the product already achieves. This is why product management generally has a say in what the developers may have listed in their release notes.
Re: (Score:2)
Release notes may not always indicate what bug fixes have actually been included. If you have an installed base you may not wish to signal an unpatched vulnerability in the field to the unscrupulous. You may also be somewhat vague about a fix that enables the product to achieve the specification which marketing claims the product already achieves. This is why product management generally has a say in what the developers may have listed in their release notes.
Fair enough. So how about we treat security flaws separate from logic flaws where possible?
Imaginary Software 2.7.3.21a
SECURITY: Fixed critical issue allowing remote code execution and remote data access and alteration... upgrade NOW
SECURITY: Fixed critical issue allowing malicious input files to cause software to upload all your data to an attacker's server
BUGFIX: Fixed bug that prevented drag & drop of widgets on screen #3 on Tuesdays when using Brazillian codepages
BUGFIX: Fixed bug that cause
Tell me *something* (Score:3)
Maybe not appropriate for release notes (which I agree with others here who suggest they should be to the point and functional) but I just wish more software developers or the companies they work for would just tell me one thing:
What does this application actually DO?
I tire of marketing-speak and general superlatives when the app name is cryptic or cute, something somebody thought was clever, but doesn't actually identify the app's function. So you have to read the marketing blurb, which far to often doesn't say what the thing does, or uses acronyms that someone who uses the software would know but someone who wants to know if it will be useful may not.
Really why does this have to be like pulling teeth?
Oh, and let's drop the word "actually", can we? About 98% of the time, dropping that stupid word from speech, reviews, or marketing enhances the clarity. It usually doesn't mean anything in the context of what is trying to be conveyed. I don't know how it became some kind of language crutch for tech about a bazillion years ago, but please, just stop it. Already.
Re:Tell me *something* (Followup) (Score:2)
" ... What does this application actually DO? ..."
It may seem strange, considering my rant, but I felt I used the word "actually" in a relevant manner. It was carefully chosen; I considered dropping it; I could have dropped it and the meaning would not have changed, but it emphasizes the question posed, versus the typical "you can actually charge the battery" drivel you usually see and hear.
Short and clear (Score:3)
Unfortunately, most release notes are hum drum and uninformative: "bug fixes, performance improvements." That may be accurate, but isn't useful
Yes - nobody cares, except the geek who wrote the stuff and possibly their mother.
A well-written release note should contain the following: .... "
1.) A single sentence that describes what the software does. No acronyms. Just a functional "This app is a music player for
2.) What platforms it works on. What other stuff is required for it to run
3.) What it does that is different from all the other applications in the same class
4.) What functional changes and new features make this version worth updating to
5.) Any killer bugs that have been fixed in this version
If the author cannot think of a short piece of text that fulfills any of those 5 categories, there is probably no reason for making this release. And even less for anyone to download it,.
Re: (Score:3)
Re:Short and clear .. and everywhere (Score:2)
Why in all the world would you put 1) - 3) in a release note?
Because you can never be sure that any piece of documentation won't be someone's first exposure to a piece of software. So for the sake of a few lines of text there is no reason to make the note user-hostile.
And given that release notes will be popular targets for searches, and their recent release will push them up search rankings it is not surprising when someone who has heard of an application and searches for it, find this first of all.
And finally: when did a little bit or relevant information ever
If it ain't broke... (Score:5, Informative)
Ever since I updated a freeware app only to find that the updated version had a rottener GUI , **and** spawned ads, I've learned not to update any app which is working nice and fine for my wants and needs.
I mean, really: My teensy freeware "spirit level" phone app works just fine. I have no idea what the last 6 updates did, and I really don't care. Nothing good can come of updating "blind" with no easy rollback path.
Re: (Score:2)
I find it's best to avoid apps when possible. If you just google "spirit level" on your phone it brings one up, no installation necessary.
apps: same rules as for Open Source release notes (Score:1)
Describe what changed (Score:2)
Fucking "bug fixes" and "performance enhancements" are too generic and hide problems and make it hard to diagnose problems that might occur in new releases.
This matters less with appy app store apps, but few tell you anything more than "We update our app frequently to maximize our tracking and resale of your data".
Fucking Microsoft has become the new king of major patches with almost no data, or at the very least a KB scavenger hunt to get an idea of what was crammed in.
Re: (Score:2)
If you haven't seen how Microsoft has changed the new update notes you should seriously have another look.
i.e. https://support.microsoft.com/... [microsoft.com]
From that one page you can see all of the updates for Windows 10 all the way back to RTM, the KBs for each, and the version numbers for each. It's much better than it used to be.
Adjusted to the understanding of the audience (Score:2)
"Bugfixes, performance improvements" is basically (if you're lucky) what you can expect of your audience to understand. What do you think the average user will take away from "Fixed a bug in SSL where depending on hash length and key size a meet in the middle attack was possible"?
"Fixed a bug *static*"
So why bother with more?
And the last time my release notes included ASCII art was shortly before being fired from my first job for wasting time on including ASCII art in the release note.
Worth downloading?!?!? (Score:1)
Re: (Score:2)
"Occasionally there is actually some technical backing for said reason, more often than not that reason is more directly related to you vendor bank account."
I think you are being overly cynical.
I have released software. And I have supported that released software. And I don't have the resources or inclination to support each individual point release. If you aren't running the current release, you need to update to get support.
A large percentage of reported issues with older versions are fixed in the current
Part of my day job... (Score:3)
Part of my day job* is helping my customers figure out why machines have BSODs. Very often this is driver issues. That means I spend a lot of time fishing for new drivers and looking at the release notes.
If I could, I would ask very nicely that driver publishers to include specifics about what issues are fixed when drivers are updated. If you fixed an issue that was causing 0x9 Power state transition failure BSODs in your Video driver, then please put that in the notes. Also, if it's not too much trouble please keep a running history in the changelog so I can open the changelog for version 5.10 and see what changed in 5.10, 5.09, and 5.08 without having to go fish for the release notes for each version.
I would also ask hardware vendors that repackage drivers (e.g. HP and Dell) to publish the original driver release notes instead of just a file that says "Upgrades driver to version x.yy"
* I'm a Windows Platforms DSE for Microsoft. The above is my own opinion, and not that of my employer or paid shilling for them.
Not sure about Apps, but... (Score:3)
... as an engineer for an IC company, I had to translate bug reports into firmware release notes suitable for corporate customers. (These days we automate it through a combination of JIRA and repo comments.)
For those of you who actually write release notes, what guidelines do you use?
There was no formal standard or best practices to follow in our group: the de facto standard was a balance between whatever our engineer (usually the same guy over many releases) thinks is enough info, and what our customers (also engineers) badger us about being not enough info.
Should one make any attempts at levity, or keep it strictly to business?
If somebody is reading your document, it's probably because something went wrong. They are short on time and reading a document they didn't want to deal with, trying to solve it quickly. They are already angry. All humor in documentation is thus inherently tone-deaf and insulting. It is never worth doing, and we all want to punch you.
How much information is appropriate in release notes?
You must first understand our customers: they build systems of many ICs (and don't devote a lot of time to any one vendor), their companies are segmented by function (so the driver guy and the platform guy never talk to each other, everything is write once/change never, and iterative design is a dirty word), and they are very risk averse (they think it's our job to prove to them that nothing is ever risky). Here's what we end up giving them:
* Bug fixes: Sometimes too many little ones to be worth enumerating, collected under "bugs fixed". But usually there are some big ones, or at least specific ones that your customer noticed and called you on. Give a description of what the issue did and something that suggests you traced it to root cause and didn't just move data around until a test passed. "Resolved an issue whereby the widget exhausted streamer overhead and data was lost." An ugly fact: giving too much detail about what went wrong and how you fixed it actually makes customers ask more questions, which means more busywork. (The Japanese notion of process means asking a lot of nonsensical questions, to be answered in the form of a spreadsheet, repeating ad nauseam.)
* Errata: customers won't always move to the latest/greatest firmware: they'll stick with what they last validated internally. Some bugs were found to be around for a long time. You need to note these newly-known bugs in your errata for the previous releases when you rev the document. This is covering your ass; you've warned them. Also, it lets you sum up many bug fixes as "fixed all other previous errata".
* New unexpected features: If a customer does actually upgrade mid-project, it'll be to fix an intolerable bug, and then they'll get new features they weren't expecting along with the fix. Assume that the release notes are the only new document that they will ever read after switching... and thus the only document that describes new features. Give the interface, an example, and any required system configuration changes needed to live with it. Think of it as a one-page white paper on the new feature.
* New expected features: "(finally) added support for Industry-Expected Feature." Done. (Paradoxically, the bigger the new feature, the smaller the release note comment can be.)
* Changed/removed features and changed interfaces. Most customers will hate that you change an interface at all, but it's unavoidable.
On a related note: early in life, I found that I'm the only one I know who ever reads help files, release notes, and EULAs. I taught myself Matlab as a grad student in about a week by using their immaculate help system. I knew about long-standing but poorly-advertised features and bugs my coworkers didn't, because I actually read the damn release notes. I was not surprised at all that my mother-in-law's Samsung TV is spying on her, or that Windows 8 phoned "home" to various universities, because they told you they were going to do so in the EULAs. If you don't read the documentation, you're going to be worse off. If you're an engineer who thinks documentation is a "someday" task or a "check box item" for a release, then you're horrible, and I hate you.
Release Notes are crap (Score:2)
The epitome of laziness:
* Bug-fixes
No Shit,Sherlock! What specifically did you fix??? As a customer I want to know does it effect me? I can't tell that when the list is nondescript.
Giving some vague description is fucking useless.
sorry i bored you (Score:1)
i am sorry i bored you with my stale and humourless release notes. I will try to insert a meme, witty comment, or try to remove herobrin next time. Who needs to maintain a serious tone when doing serious business, am i right ?
Notes For No One (Score:2)
User visible changes (Score:2)
Release notes don't have to be very detailed (you have the git repository for getting all the details), and they should not mention anything the users don't care about. What is most important is that all noteworthy user visible changes are listed.
BIOS updates with empty change logs (Score:2)
As one user in a forum rightfully commented it: "Installing the latest Asus BIOS with empty changelog on your mainboard feels like sleeping with the filthiest crack-whore around, just hoping you'll stay healthy."
MariaDB (Score:2)
While I understand why not all software can follow this formula, I do personally appreciate what MariaDB does.
On the main page for each version, they have a small summary of major changes/features/fixes. And then they have a link which goes to a commit log of every single code change. Each of these items in the log lists the Git commit summary along with a Github link to show the exact changes made to the code base. This is additionally nice, as it shows WHO is contributing WHAT to the MariaDB code base.
NY Times Crossword (Score:2)
# Fixes
- Fixes a crash on launch for some users.
- Fixes a crash when some users try to log in.
- Fixes a crash when restoring purchases fails for some users.
- Fixes a crash for some users after logging in during the onboarding process.
# Fun Facts
CRASH has appeared as an answer in The New York Times Crossword eight times and BUG has appeared 15 times. No wonder SORRY has appeared 16 times.
Making release notes useful (Score:2)
I wrote release notes for operating systems and compilers for nearly 40 years, and it was never an easy task. New features aren't the issue - they're usually straightforward to describe. It's bug fixes that sometimes had me tearing my hair out. For each one, based on the developers' notes and (sometimes) the original problem description, I had to figure out what I could tell a reader that would help them recognize the exact problem that was fixed. In many cases, the problem was exposed only under specific c
Paper trail (Score:2)
Is how I've always viewed them in my environment.
You can't bullshit your way out of a random change. Intentional or not. And with very good reason!
Sometimes the odd dev (guilty...*) will try to sneak in a change in an unrelated issue. Since the release notes contain all issues fixed since the last release, you can just bring up the changelist and go *AHA!*. Internally this is not usually an issue as nobody actually checks changelists unless a nasty software issue arises, and damn you if you caused it throug
Re: (Score:2)
strange log (Score:2)
I find computer games have the best release notes:
https://twitter.com/TheStrange... [twitter.com]