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.
Legit users should stay up-to-date, for security and support related reasons. It's always lame trying to support someone whose software is several revs back. Update your shit and try again.
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.
"Cu the clowning and tell me what I need to know" sounds about right to this tech writer.
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.
" ... 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.
and keep the marketing bullshit to yourself.
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
The following is the bare minimum I would expect out of any competent release notes made for the general public.
__
Name Of Product
Version Number
[Optional] Lay description of what the intent of the release is. Best to include this to sell the reader on the reasons why they should update to the latest version. [/Optional]
New Features
-
Updated Functionality
-
Bug Fixes
-
/. 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
But Bit Blaster XL had a great requirements page on Steam when I got it the other day :)
Being an 8-bit arcade game they had a little fun.
https://github.com/coreinfrast... covers this, e.g., "human-readable summary of major changes in that release to help users determine if they should upgrade and what the upgrade impact will be" and "MUST identify every publicly known vulnerability." The main difference is that, for apps, the interests of the developer are less often aligned with the interests of the user. The essence of a new release can be "more features but also more ads."
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.
"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.
We used to have a Bill of Rights. Now, with the rights gone, all we have left is the bill.
"That may be accurate, but isn't useful for determining if the new version is worth downloading." Last I checked most updates getting downloaded has absolutely nothing to do with whether they are worth downloading. It has much more to do with your phone, game or other internet connect software forcing you to update or simply annoying the shit out of you until you give in. If you do actually find release notes before being forces to update, the content of them is pretty much mute. Whatever entity that decided you need to update is going to force it on you. I know enterprise techs have somewhat more control here than consumers, but they still deal with if you want to do X you have to version Y for no other reason than we said so. 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 would definitely consider it over the competitor.
Aye, we be happy t' announce t' release o' Cython 0.15.1. Step to,
thar be no better time t' set sails fer http://cython.org or
http://pypi.python.org/pypi/Cython/ t' download the loot.
We be bugfixing-only this release. Arrr, behold the list o' scallywags
sent to Davy Jones' Locker:
http://trac.cython.org/cython_trac/query?group=component&milestone=0.15.1
. Ye motherload at
https://github.com/cython/cython/compare/0.15...0.15.1
We be much beholden to ye hearties fer manning ye oars: Stefan Behnel,
Robert Bradshaw, Armon Dadgar, Mark Florisson, Gordin, Angus
McMorland, Vitja Makarov, Ralf Schmitt, and Yury V. Zaytsev. We also
be most grateful to ye landlubbers reports o' sad tails o' bugs.
Fair winds!
https://mail.python.org/pipermail/cython-devel/2011-September/001428.html
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.
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 hurt an end user? You add this stuff because there is never a good reason not to include it in EVERY document concerning a software release.
politicians are like babies' nappies: they should both be changed regularly and for the same reasons
... 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.
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.
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 ?
"life is a joke, and someone is laughing at me"
The vast majority of users have automatic updates turned on (which is the default in iOS) so all updates are downloaded automatically and they never see the release notes. Of those that do manually update, I'm sure only a small percentage of them bother to read the update notes. Why bother if only maybe 2% of your users look at your notes? Seems a waste of time and effort which could be put towards more important things.
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.
Asus recently started a habit of providing zero-sized changes informations (instead of the information-depleted, terse "improved stability" texts they provided before).
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."
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.
At least on Android, most significant apps maintain the ability to roll-out features gradually, even after the binary has been downloaded. This allows, for example, the ability to disable a feature with an unexpectedly high crash rate when it is detected after deployment. The consequence of this is that even interesting features may not be described in release notes, because not all users will see them immediately after downloading the update.
My favorite release notes were for a bug fix in the NYT crossword app:
# 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.
while [ 1 ]; do echo -n -e "\xe2\x95\xb$((($RANDOM&1)+1))"; done
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 combinations of uses (especially for compiler bugs), and there was no clear-cut way of describing these.
Worse, from support and development's view, were customers who had not reported a problem themselves, but saw a description that vaguely matched what they were seeing and they'd complain that "the bug wasn't fixed". Of course, THEIR version of the bug was different from what was behind the release note.
The primary purposes of release notes, in my view, are to highlight changes in behavior or requirements that users need to know about. Lists of bug fixes are a high-effort task for low user benefit, and indeed my former employer stopped providing bug fix lists in recent years.
The little snippet release notes for apps are very vague summaries of changes, and I don't at all blame developers from writing "Bug fixes and performance improvements" over and over. Yeah, the entertaining notes are, um, entertaining, but I agree that they're more a promotional thing than an attempt to educate users.
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 through the above-mentioned shortcut... Externally though, try it and you'll likely get your ass handed to you.
*Being a "get things done" kind of person... I tend to take too many shortcuts/juggle too many tasks at once. It's worked most of the time (internally) but I've sweat a few bullets in my meager time as a soft.dev. regardless. It's also a lot of un-required stress (unless you just don't care). Take. Your. Time. Folks.
I tend to rant.
I discovered several years ago that there is an accelerated release process when the message for the app approval reviewer is "bug fixes". Turnaround time to approval is about 6 to 12 hours. If you even mention that you added a new feature instead of just saying "bug fixes", then the turnaround time becomes 2 to 4 days.
It works every time. If the app is crashing or not working, it's far better to just say "bug fixes" and get the fix pushed through the approval queue than watch the 1-star reviews and uninstalls rack up. And it's better to say "bug fixes" than to spell out what's actually changed for new features if it means you have to wait for Apple's and/or Google's blessing. Everyone has automatic app updates turned on anyway (except for nerds), so no one actually cares.
I used to place cute ASCII Art animals in random scripts as a reward for proper execution. Nothing like an ASCII squirrel appearing to brighten your day.
I object to power without constructive purpose. --Spock
Do you need a Loan to finance your company
Are you looking for financial assistance, are you in desperate need of funds ? Lugard Rose Loan Firm is here to provide you the loan amount requested. We give loans at a standard rate of 2% reach us via: lugardroseloanfirm@outlook.com
We offer various types of loans include: Business Loans, Personal Loans, Home loans, car loans, student loans, debt consolidation loans, unsecured loans, venture capital,Xmas loan etc. Contact us today via lugardroseloanfirm@outlook.com and get a legit and easy loan today.
Thanks
Await to hear from you soon
Next I asked if I could stop writing them, but got told, "No." So much for data-driven decision making.
I find computer games have the best release notes:
https://twitter.com/TheStrange...