Giant If

On Release Notes

Release notes, amiright? Who reads ’em? Well, me, and not just because because I create them myself.

For example– just for fun, I used to illustrate notes from The Strange Log, a Twitter account that posts “the strange poetry of changelogs and patch notes.” I’d pick out one that made me laugh and gave me a mental image, do a quick sketch of that image, and then retweet the note along with my sketch. Didn’t get much traction, but then, that was 2015.

I also write release notes, although I haven’t– yet– been allowed to illustrate those.

What matters?

Release notes can actually vary considerably in tone, length, terminology, and format while still achieving their primary purpose (providing information about new features, updates, bug fixes, etc. in the new release), depending on the product described in them and the audience consuming them. Each of those traits is very important, but also can– and should– be tailored according to context.

I think a few primary areas of emphasis remain constant, however:

  • Information accuracy. If I opened the product right now (assuming I’m not already in it) and tried to use this new feature, would I see it? Would it function as described? Would I know what it’s for, even if I’m not sure how to use it?
  • Accessibility. Do I even know there was a release, let alone that I can read about what’s in it?  If I want to read about it, how easy is it to find that information? Are there gratuitous obstacles that prevent me from consuming it, if I’m disabled?
  • Content that users need/want to know. No more, and no less.  What will surprise them the next time they open the product? What will potentially confuse them? What’s happened on the back end that they can’t see, but still might care about very much? What’s a feature they’ve been requesting forever and it’s finally here? What was broken and is now fixed, so they can use it with confidence going forward?
  • Blatant bragging about what’s new and cool. Self-explanatory, I think.

And as I alluded to with the “no less,” a seemingly interminable release notes doc is nearly as bad as having no release notes at all.  Perhaps even worse, as in cases where a user might shudder and close a tome of notes accompanying the new release, missing out on a bullet list on page 37 saying something they really care about.

Where do you even start?

Regardless of how big or small the product is, how many people work on it and how many use it, if it has releases, most of the heads determining the direction of the product will be deciding what goes in the release notes. Inevitably there’s also a tech writer trying to wrangle it all, while simultaneously desperately trying to set up an intravenous method of coffee delivery.

To manage these disparate channels of information, the writer may create a shared document and request that it be populated. They may take part in a regular release meeting. They may use a tool to divide and classify updates and bug fixes according to source and category. And they may write the whole thing from top to bottom with almost nothing to go on, or they may take part in an established process where everybody knows what they’re contributing and does so reliably, even cheerfully.

Please note that I’m writing from the perspective of that tech writer,  not intending in any way to denigrate or downplay the efforts of everyone else in the development cycle, when I say that corralling all of this content into one place and turning it into something coherent, let alone readable, let alone useful, is a big ask.

 

 

 

EDCs

WK release notes in Lotus Notes and Flare project

Bravo Notes overview