Author Archive

Deb Kuykendall

Deb Kuykendall

Principal Technical Writer at EMC Isilon Storage Division
Deb Kuykendall

Latest posts by Deb Kuykendall (see all)

All about improving EMC Isilon OneFS release notes

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):

OneFS 7.1.1-7.1.1.5 release notes

And here’s an example of what you’ll find in the Adobe Acrobat or Adobe Reader bookmarks pane:

OneFS 7.1.1-7.1.1.5 Bookmarks

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:

http://bit.ly/isi-docfeedback

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.

[display_rating_result]

All about EMC Isilon OneFS release notes

As you prepare to upgrade your EMC Isilon cluster to a new version of OneFS, you probably want to know the following information:

  • What new features are in the release
  • Which issues are fixed
  • Whether any issues involved with the new release could affect you

All this information can be found in the OneFS release notes. The release notes serve as the primary source for information about fixed issues, new features, enhancements, previously released patches, and known issues that affect the release.

How to find release notes

Currently, two sets of release notes are published for each supported OneFS branch. The initial release note is published when a new major or minor OneFS release is released (for example, 7.0, 7.1.1, and 7.2.0). Subsequently, new maintenance release (MR) notes are published whenever a new maintenance version for a particular branch is released (for example, 7.0.2.12, 7.1.1.2, and 7.2.0.1). The initial and maintenance release notes contain similar information, but there are a few differences.

All OneFS release notes are available in PDF format from the EMC Online Support site. The easiest way to find them is to go to support.emc.com and search for “OneFS <your 3-digit release number> release notes.” For example, if you’re running 7.0.2.12, search for “OneFS 7.0.2 release notes.”  You’ll find both the initial OneFS 7.0.2 Release Notes and the OneFS 7.0.2 MR Release Notes.

Searching for OneFS 7.0.2 release notes on the EMC Online Support site.

Searching for OneFS 7.0.2 release notes on the EMC Online Support site.

For more information about OneFS major, minor, and maintenance releases, see knowledgebase article 89210 on the EMC Online Support site.

What you’ll find in release notes

Release notes contain summary descriptions of issues that are fixed in the release, and known issues that affect the release. But it’s important to note that these lists aren’t all inclusive. We provide information about fixed and known issues that Isilon customers have reported or might encounter. Some fixes and known issues that affect OneFS code under-the-hood, and don’t have a known customer impact, aren’t included in the release notes.

The initial release notes contain information about functionality changes between the previous major/minor OneFS release and the current one—for example, changes in the formatting of CLI commands. They also contain summaries of new features. The MR release notes don’t contain feature and functionality information, but do contain information about previously released patches that are included in the release. In most cases, the initial release notes don’t contain any information about patches.

Structure and content

Initial and MR release notes contain a standard set of topics, as you’ll see in this screen shot from the 7.1.1.2 maintenance release notes.

7-1-1-2 toc_v2The Upgrading OneFS topic contains information about where you can find system requirements and applicable patches for the release, as well as the list of OneFS releases that can be upgraded to the documented release.

The release note also contains tables listing enhancements that were added in the release—for example, new command options—and issues that were resolved (that is, bug fixes). In maintenance release notes, the Enhancements and Resolved issues topics are cumulative and organized by maintenance release number.

The patches topic, which is relatively new to the release notes template, contains a table listing previously released patches that were included in the current maintenance release or a preceding maintenance release.

Improvements over time

Over the past few years, changes have been made to improve the ease of use and overall quality of the release notes. For example, because MR release notes are cumulative, they can become quite long. To fix this, we removed some information that can be accessed in other product documents, such as the upgrade instructions.

We also responded to requests to add patch and hardware compatibility information. For example, information about previously released patches can help you to confirm whether or not a later release includes the fixes from a patch that you’ve installed on your cluster.

Finally, we understand that cross-referencing two different types of release notes can be challenging, and that it might not always be clear which document contains the information you need. Looking ahead, we plan to combine the initial and MR release notes into a single document. This document will contain information about functionality changes and features that were introduced when the major or minor release was made available, but it will also be updated to include information about the most current MR that’s available for download from the EMC Online Support site.

Provide us with your release notes feedback

Do the release notes provide the information that you really need? Does the format help you find the information you’re looking for?  Please take a minute or two to help us improve the release notes so we can learn about ways to better serve your needs.

 

Start a conversation about Isilon content

Have a question or feedback about Isilon content? Visit the online EMC Isilon Community to start a discussion. If you have questions or feedback about this blog, or comments about the video specifically, contact us at isi.knowledge@emc.com. To provide documentation feedback or request new content, contact isicontent@emc.com.

[display_rating_result]