Wheat and Chaff in Software Release Notes

Omni Group, the Seattle-based software artisans, have made a name for themselves by creating applications with very meticulously crafted user interfaces. One of their products, the GTD-inspired task manager, OmniFocus, is among the few applications I simply could not live without anymore.

Who moved my actions?

In a recent release, the developers changed a detail in the way OmniFocus displays its data. Due to this change, some data views in the software would now display many more items.¹

Lists that previously were tidy, and easy to grasp and to handle, …

… were now swamped with data items.

In case you’re wondering: yes, the source data for both of these screenshots is identical! (Note the size of the scroll bar thumb to get an idea of the total length of this list.)

It only took a few days of working with the new version before I got so frustrated with this new flood of data that I decided to send a feature request to Omni Group, asking them to add an option in an upcoming release that would bring back the old behavior.

And I still haven’t found what I’m lookin’ for…

What I hadn’t realized was that the option that I was asking for had already been added — in the very same release as the display change itself. And yet, I had only found it after reading about it in a tweet. Why hadn’t I found that option myself?

Because I could not see the forest for the trees. Twice.

At first, I had searched OmniFocus’ preferences panes for a way to restore the previous behavior, and had come up empty-handed. Then I scanned the menus and failed again in my search, even though the option in question takes center stage in the View menu.

OmniFocus is very flexible in terms of how it displays its data. Consequently, the View menu has lots of items and plenty of sub-menus. What’s more, at the time I did not know the exact name of this option, of course. And so I literally overlooked what I was searching for.

In that sense, the View menu is forest number 1, so to speak. Forest number 2 are OmniFocus’ release notes.

Release notes of novelesque proportions

Omni Group always provide extensive release notes for all of their applications. Generally speaking, I very much welcome such a level of detail, but it also comes at a price: the sheer amount of information makes it almost impossible to filter out the chaff of countless bug fixes and internal code changes.

Consequently, trying to concentrate on the more useful and important tidbits — from an average user’s point of view — like changes in UI or behavior, is tedious and tiring.

Agile Web Solutions have found a nifty fix for this problem: they label each item in their release notes with colored “New,” “Changed,” and “Fixed” tabs.

By scanning for the “New” tabs, you can easily discover new features in the software that you may want to try out and, possibly, learn how to master.

“Changed” notifies you of changes to existing features that you may already be using, so that you can quickly learn how to adapt to these changes.

And finally, chances are that you can safely skip any items labeled “Fixed,” unless you have been plagued by a certain bug and you now want to find out whether this bug has been fixed yet.

To make these labels truly useful to the user, it is essential that the categorization reflects how the application has changed from the user’s point of view.

In other words, the “New” and “Changed” labels should only be used for new features and changes that manifest themselves in the software’s UI, and not just “under the hood.”

Any modifications like code optimization, data schema changes, protocol adaptations, etc. belong in the “Fixed” category unless they require the user to take action because of them.

Take, for example, the top-most “Changed” item in the screenshot, “Added a workaround…”. From a developer’s perspective, that surely is a “Changed” item, but since the user will not see any differences in the software’s UI because of this change, it should have been listed as “Fixed.”

For release notes as extensive as Omni Focus’ software’s, labeling each and every bullet item would amount to visual overkill, but separating these bullet items into three categories “new,” “changed,” and “fixed,” should be perfectly feasible.

Detailed release notes are a valuable part of the overall documentation of a software application. Classifying the list items as “New, “Changed,” and “Fixed” would make even lengthy, verbose release notes more easily digestible for average users while, at the same time, keeping the information they contained as detailed as expected by expert users and developers.

Update 2011-02-08: My text notes application of choice, Notational Velocity, provides another example for very cleanly laid-out release notes. These are sorted into three categories: “New Additions,” “Behavior Changes,” and “Fixes.”

All of the items found in “New Additions” and “Behavior Changes” do affect how the user interacts with the application, and do not reveal any under-the-hood details related to these changes. Such technical details are found exclusively in the “Fixes” section, which refers to, e.g., proxy servers or programming frameworks — terms and concepts that may confuse average users.

Unfortunately, the notes for the update shown here include an important note about compatibility issues, which is placed at the very bottom of the release notes.

Users who only take a casual glance at the release notes before hitting Install Update will likely miss this note. This pitfall could be easily avoided by placing warnings like this one at the very top of the release notes.