More thrilling tales of release notes (part 2)

In my previous post, I described how I structure release notes, and what sort of content I include in them. This time, I’m going to focus on gathering information, when to release the release notes, and how to let your users know that they exist.

Hunting and gathering

The first step is to identify your subject matter experts (SMEs). That’s rarely a single person, but that’s true for any content that you’re going to write. Maybe the “who” part is too obvious to most tech writers; instead, the difficult part is the when and how.

“When” is going to depend on your release schedule: Are you following the traditional waterfall process, with long release cycles? Then you’ll have loads of time, and can start the release notes a month before the release date. And then add to the release notes as your engineering team squeezes more changes (usually fixes) into the release at the last minute.

But for most of us…

If you’re hip and trendy and agile, then you’re looking at much shorter dev cycles, and probably shorter release cycles. Typical in my experience are monthly or biweekly releases. Some of those include “internal” fixes, things that won’t be visible to your customers. Those are the best ones from a writer’s standpoint, since we can slap on some boilerplate that reassures that customer that we’re working on stuff, even if it’s not visible (other than a change to the version number).

But most releases include at least a feature or two, and hopefully a fix to an issue that a customer reported. That’s when you need to schedule those meetings with the SMEs. In a short dev cycle, that can be a couple of days before the release; but it also means that the release notes will be relatively short, so a couple of days is enough time to write the content, get it reviewed, and publish it.

Getting ahead of that schedule by basing release notes on the list of tasks scheduled for the sprint is a good idea, but not without risks. Some of those features/fixes might not be completed (which means using that content for the next release, so no loss there), or a few things might get added to the release. But it’s rare that the release changes entirely, and I find those risks are well worth the ability to give myself a bit more time.

After all, are you ever focusing on one task at a time, with the ability to devote all of your attention to it for an extended period?

Sending them out into the wild

When to release the release notes is an interesting question. At least it is to me. Many companies default to publishing them as soon as the release itself is available to users (or pushed to their clients, or the app is updated). Other companies have asked me to release them earlier than that, to give users notice of upcoming changes.

I like releasing them a little early; I agree that customers should have a bit of notice, and a chance to update their processes, or just look forward to new features and fixes. You’ll need to avoid confusion, at least as much as possible, by clearly indicating when the features and fixes will be live. I’ve had more than one customer complain because they aren’t seeing a feature that hasn’t gone live.

In those cases, I don’t blame the customer at all. They’re skimming the release notes for the interesting bits (interesting to them), and it’s easy to miss a message about the release date.

So if you do publish the release notes early, don’t bury the timing information! Slap it in an IMPORTANT! block, put a box around it and give it an eye-catching icon. Honestly, it’s just too bad that we can no longer use the blink tag in HTML. Or marquee. Or 72-point red blink marquee with dancing hamsters.

Here Ye, Here Ye!

So now you’ve researched, written, and published the release notes. Which doesn’t matter at all if no one reads them. Putting them at the top of your documentation site or knowledge base is fine, but how will your users know to look there?

To be honest, I’m facing this same problem, myself. I like what Trello has done, with a visible, but unobtrusive popup icon to let you know about new or upcoming features. I’d like to do something similar, but it is a nice-to-have feature. Our engineering team is focused on must have features, so it will be a while before that’s added to the product.

For now, I’m doing what I can: I’m making sure that release notes are visible when users log in to the knowledge center. This means putting them at the top, “above the fold,” and marking the latest release note topic as a “featured” topic. This means that it gets a very visible, bold and highlighted title.

But it still requires users to log into the knowledge center to get that information. And that’s a big leap to expect them to take without guidance.

So it’s still a work in process, but at least I have a goal in mind. Until I figure out a new way, and a new goal, but that’s what makes the job fun.