Back in February, I wrote about EMC Isilon OneFS release notes and hinted that we’d be making changes to the format to improve their usability. I’m happy to announce that these changes are now in place and that you can see them in the OneFS 7.1.1 release notes.
What’s Changed
We’ve merged all of the release notes pertaining to a release branch (for example, 7.1.1) into a single document. This means that the 7.1.1 release notes contain all of the information about this OneFS branch from OneFS 7.1.1.0 (released in August 2014) through 7.1.1.5 (released in June 2015).
The new document includes:
- All the new features that were introduced in OneFS 7.1.1.0 through OneFS 7.1.1.5
- All the issues that have been addressed in in OneFS 7.1.1.0 through OneFS 7.1.1.5
- All the functionality changes that were introduced in in OneFS 7.1.1.0 through OneFS 7.1.1.5
What’s New
To improve the document’s usability, we defined a list of functional areas. And, to help ensure that the functional areas are well understood, we included the full list of functional areas and their definitions at the end of the release notes. For example, the functional area of SMB encompasses new features, changes, and issues that affect SMB environments.
The content in the release notes is organized first by release number (for example, OneFS 7.1.1.2) and then by functional area. This means that if you want to know if there are any new features, resolved issues, or changes in functionality that affect a particular area, such as SMB, in a specific OneFS release, such as 7.1.1.5, you can use the bookmarks pane or the table of contents to easily find that information.
Here’s an example of what you’ll find in the new table of contents (TOC):
And here’s an example of what you’ll find in the Adobe Acrobat or Adobe Reader bookmarks pane:
We’ve also added an introductory section for each chapter, describing what you can expect to find there.
The new document also highlights the Target Code release. This change helps you understand how the Target Code release relates to other releases in the branch.
What did we gain?
Before making these changes, if you wanted the full picture of a OneFS release or maintenance release, you’d have to download two or three documents and piece them together. Each document contained some unique information, such as new features, and some overlapping information, such as known issues. The differences weren’t always obvious.
Now all of the information is in a single document that clearly identifies the release in which a fix, a change, or a feature was introduced.
In addition, the release notes previously contained multiple, lengthy tables that were sorted by a cryptic ID number. If you wanted to find issues related to a specific area of operation, you’d have to do a keyword search and collect bits and pieces of information scattered throughout the document.
Now the information is categorized first by the release in which the feature, fix, or change was introduced, and then categorized into tables according to the functional area that the feature, fix, or change affects. The new tables are small and easily scanned, and the information they contain is tightly focused.
How we did it
Developing the new release note format was a team effort involving writers, an information architect, and members of our user experience team.
We conducted user testing and issued a survey about the new format to confirm that the changes we planned to implement were in fact improvements that would benefit our readers. The feedback we received from user testing influenced the development of the document.
For example, one of our concerns early on was that the document was too long. However, user testing indicated that our users don’t read the document from beginning to end. Their chief concern is finding specific pieces of information easily, and they tend to jump from one place to another using keywords, the table of contents, or the bookmarks pane. So document length is not an issue.
Also, we had initially planned to separate new features from changes in functionality. User testing showed that our readers expected to find all of the new and changed features and functionality in the same chapter.
The most striking piece of feedback? Categorizing the information by functional area scored as a significant improvement for all of our testers.
Here are some of the usability testers’ comments:
- “This is so great! Seriously. This is so much more legible and issues are so much easier to find.
- “For me the redesign is a massive improvement over the current format. I hope this new format can be the new standard.”
- “Known issues clearly separated by topic is a huge gain in usability. A consolidated listing of known and resolved issues for the major + each MR in one location is a time saver. If I have to attempt several keyword searches to find what I need, it takes me only 50 percent the time to do this in a combined doc.”
What’s next
As of today, the new release note format has been implemented in the OneFS 7.1.1.0 – OneFS 7.1.1.5 release notes. By the end of July, the new format will be implemented in release notes for the OneFS 7.2.0 branch as new versions of OneFS are released, the new release note format will be used to document those releases.
A new project to evaluate whether the new format can be applied to the release notes for other EMC products will be underway soon.
We’d like to hear from you about the changes and how they affect your ability to use the OneFS 7.1.1 release notes. You can provide feedback by taking the short survey located here:
Or send an email to docfeedback@isilon.com.
These links are also available in the OneFS Release Resources section of the OneFS 7.1.1 Release Notes.