Slashdot is powered by your submissions, so send in your scoop

 



Forgot your password?
typodupeerror
Software

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?

The Strange Art of Writing Release Notes

Comments Filter:
  • by king neckbeard ( 1801738 ) on Tuesday November 14, 2017 @11:45AM (#55547903)
    Release notes should generally be functional. Save the marketing for a new update for a press release.
    • Re:Functional (Score:5, Insightful)

      by El Cubano ( 631386 ) on Tuesday November 14, 2017 @11:51AM (#55547955)

      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.

      • by waveclaw ( 43274 )

        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

        • published in a convenient "permanent" location
        • provided in multiple formats (direct email, mailing lists, usenet, webpages, version control strings, package logs)
        • searchable format (text)
        • ordered reverse chronologically (newest first when reading top to bottom)
        • available in common languages
        • clearly written in short, technical language
        • mentioning new features including searchable st
      • by AmiMoJo ( 196126 )

        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)

      by freeze128 ( 544774 ) on Tuesday November 14, 2017 @11:57AM (#55547999)
      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!
      • 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.

    • by fermion ( 181285 )
      I think that release notes are seen as marketing. This makes sense for some free Apps. Most Apps are downloaded and never used, so the update provides an opportunity to communicate with users. Rover does this, as well as lyft and Google with it's 'fresh new look'.

      What I find amusing is when MS thanks you for using their office suite, like most people have a choice.

  • Slashdot readers are highly opinionated jerks.

    Oh, wait. That's not what you were asking? Well you suck.
    • /. 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.
  • by Wrath0fb0b ( 302444 ) on Tuesday November 14, 2017 @12:01PM (#55548031)

    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.

    • >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

      • 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.

    • By the time I read the release notes I could have downloaded and installed the new version two times. Very rarely does anyone need release notes. Just install and pray.

  • by coastwalker ( 307620 ) <acoastwalker@hotm a i l . c om> on Tuesday November 14, 2017 @12:05PM (#55548063) Homepage

    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.

    • 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

  • by gordguide ( 307383 ) on Tuesday November 14, 2017 @12:07PM (#55548071)

    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.

  • by petes_PoV ( 912422 ) on Tuesday November 14, 2017 @12:16PM (#55548137)

    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,.

    • If there are bugs that affect 1% of your user base, and you fixed those because they were loudly chirping to you or because it was easy to fix, but you don't really want to panic the rest of your user base by implying the bug is a big deal, I can easily see, "Fixes a rarely encountered bug" without getting into details. I think the rules are different for consumer software than for corporate software -- with commercial software, the upgrade notes are as much or more about brand building as they are about te
  • If it ain't broke... (Score:5, Informative)

    by cellocgw ( 617879 ) <cellocgw@@@gmail...com> on Tuesday November 14, 2017 @12:23PM (#55548197) Journal

    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.

    • by AmiMoJo ( 196126 )

      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.

  • https://github.com/coreinfrast... [github.com] 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.

    • 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.

  • "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.

  • "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 decid
    • by vux984 ( 928602 )

      "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

  • by ElizabethGreene ( 1185405 ) on Tuesday November 14, 2017 @01:31PM (#55548737)

    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.

  • by Ghostworks ( 991012 ) on Tuesday November 14, 2017 @01:49PM (#55548899)

    ... 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 ?

  • 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.

  • 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.

  • 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

  • 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

  • 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 find computer games have the best release notes:
    https://twitter.com/TheStrange... [twitter.com]

The number of UNIX installations has grown to 10, with more expected. -- The Unix Programmer's Manual, 2nd Edition, June 1972

Working...