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 is my signature. There are many like it, but this one is mine.
Slashdot readers are highly opinionated jerks.
Oh, wait. That's not what you were asking? Well you suck.
Damn_registrars has no butt-hole. Damn_registrars has no use for a butt-hole.
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.
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.
Facts are history now plebs have politics for religion on social media.
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.
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,.
politicians are like babies' nappies: they should both be changed regularly and for the same reasons
/. readers are also too highly technical to provide a meaningful response on what "average" users are interested in.
Though, frankly, "average" users don't read release notes.
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.
https://app.box.com/WitthoftResume Code: https://github.com/cellocgw
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.
... 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.