Simplifying the Release Notes Process: Upcoming Release Notes Changes

[erinhmcmillan]

Over the last few years, we’ve been making constant modifications to improve the release notes for Instructure products. Recently some of you may have participated in the Canvas Community health check—a survey that helps the Community team gauge your experiences with the Canvas Community. For better or worse, we use that survey to help us find ways to make your experience with the Canvas Community even better!

We’re excited to announce that the release notes are undergoing some additional upcoming changes that will help you keep up with our product team’s latest and greatest! These changes will be effective with the August 4 release.

General Changes

Without boring you with all the small details, here are the main highlights that are coming to the release notes:

Release notes will reside in their own subspaces. You can easily access and follow release notes for one or more products without having to get notes for other products.

Why make this change?

We want everyone to be able to manage their own preferences about what release notes documents they receive. Currently, following the release notes space means you get spammed with every product’s release notes, whether you want to read them or not. Additionally, we don’t want you to have to rely on Instructure’s mailing lists as to whether or not you receive an update. We even created a new document to specifically show how to follow release notes in each space and how to manage your community preferences.

The main release notes page for each product will receive a design update that displays a summary of the last four releases. This change means that you can see what features were recently deployed without having to view previous release notes documents. Additionally, you’ll also be able to identify feature options more easily.

Why make this change?

Some products—more than others—have lots of features as part of each release. Can you keep track of which features came out in each release? Can you tell which ones are feature options or LTI tools? Neither can we. So we’ve improved historical viewing for everyone. If you can’t find what you’re looking for in the main release notes product page, we have a comprehensive list of all feature releases that we keep updated as well.

Here's an example of what the July 14 Canvas release would look like with this new page design:

Canvas-Specific Changes

Only one release notes document will be published per release. This change only applies to the Canvas release notes, since Canvas is the only product that can support this workflow. This change means that you won’t have to follow two different documents (beta and production). For example, the current Canvas release is July 14. We published beta release notes on July 2, and we published production release notes on July 9. If we already had one set of release notes now, we wouldn’t publish production release notes and just add any changes to the notes we published on July 2.  

Why make this change?

You’ve let us know that it’s hard to keep track of both documents, considering the beta notes are only published for a week before the production notes are published. Additionally, most everything that is announced in the beta release notes is included in the production release notes. With these changes, we may still need to make adjustments during the release but we’ll announce them in the same document. (And we’ve created an easier way for you to see what we change through the release, too, if applicable.)

Each release provides the full details but also summarizes features by user role. This change helps all users get the information they are looking for without having to create additional documentation.

Why make this change?

Each user role only cares about how a feature affects them. If I’m a teacher, I probably don’t care what admins can do. If I’m an admin, however, I care about how a feature affects everyone. Regardless of your role, you can view documents that show you exactly what you should care about and why. The best part is that these documents are hosted as Google docs, so they can be easily shared throughout your institution.

Want to Learn More?

If you have additional questions, feel free to leave comments below, or you can also chat with me live on July 11 in the Release Notes Changes CanvasLIVE meetup.

[ProfessorBeyrer]

This sounds like a good change. The summary by user role will be especially helpful for alerting our faculty about the changes affecting them while also prepping them for changes to their students' experiences. I am excited about easily sharing directly with students too.

[jeb5123]

Will you still have the Fixed Bugs section in the new format, or will each bugfix be their own card, or listed with the feature, or how will that work?

[victoria-maloy]

I really like the "Option" flags. This will highlight when further action is needed to turn on/make available the feature released.  Thank you!

[jeb5123]

I see that the full document still exists, but it has been altered and the video did not show that section. I just want to make sure there is a section that I can review the Fixed bugs and what the actual changes are. So would that be on the main release screen or in the full notes?

[macaulayl]

Yes, this is great!  Now, if the screencast could also be organized by user role, that would be awesome.  I would love to be able to share these videos with users, but typically it contains info for all roles so it would be confusing to share.

[kblack]

That's a great idea, macaulayl‌!  Frankly, just having an instructor-specific one would be a good first step. keeping the "regular"/full one for admins.  Of course, it would mean more work for the Canvas folks to come up with two, but perhaps not (ahem....) if the releases were, say once a month rather than every 3 weeks.  (Something I've mentioned in the past, I think!)

[Chris_Hofer]

I always embed the video in a Global Announcement for our faculty to view...even if it includes stuff for admins.

[tellison]

Thank you erinhallmark‌ for working on this.  This looks like a nice "user friendly" change.  Look forward to August 4th.

[millerjm]

Thank you... having the changes of what is different from beta notes vs. production release notes will be helpful and mean not having to compare two documents.  

[fosterl]

These look like great ideas, and I thought the current form of Release Notes were fine! Thanks as always for the pro-active approach.

[kmallette]

I'm really hoping the ability to browse by role will make faculty less terrified to read through the release notes. Trying to make the community as a whole more accessible to faculty and staff and this makes my job a little easier

[sueharlan]

erinhallmark‌

Thanks for the Canvas Hour today. The new format looks great!

[jayde_colquhoun]

erinhallmark‌ this looks great! Being a large institution, the feature release note management in our Uni is not hosted by a single department/ user. The separation based on roles will definitely help us split the ownership depending on the department looking after that area. Love the notes being in one document too! Great work. 

[erinhmcmillan]

Hi, everyone!

Thanks to all who joined us in the meetup yesterday. I'm posting a quick overview of some of the major questions that we discussed for everyone's benefit:

Is the demoed Canvas layout going to be the same across all products?

The layout will be modified to fit each product, but the structure will be the same. Each product will provide a visual summary of what is in the release. Products include Canvas, Mobile, Canvas Data, Arc, Gauge, and Catalog. Commons will be archived as updates are being included in Canvas notes.

Canvas is obviously the largest and most complicated, but each product will reside in its own subspace, making it easier to follow only the product updates that you care about. Four of the five buttons at the top of the Canvas page won't be part of all products—Canvas is the only product that will have user summaries, screencasts, beta environment chats, and the API change log.

How soon in the process will you publish all the supplemental release details for Canvas?

• The API change log is published on or before the day the release notes are published.
• The goal for user summaries is to have them available with the release notes, although be aware that like the release notes, user summaries are subject to change. 
• The beta chat takes place a few days after release notes are published and is a recurring scheduled CanvasLIVE event.
• The new feature screencast is published the Monday before the production release.

Do these changes affect deploy dates for beta/test refreshes?

No. Beta and test will continue their regular refresh schedules respectively on Saturdays. What is the Canvas release schedule for beta, production, and test environments?‌

Has any feedback been taken from instructors and has it been considered as part of the user experience?

Yes! Our community health check contained hundreds of responses from respondents identifying themselves as not being responsible for communicating change to their institution, which means we have lots of instructors finding out what is in the releases! (We've also had a few students comment occasionally, but primarily we're noting our audience is primarily admins and instructors.)

Additionally, the comments asked that they have a summary of what features affect them, hence our user summary documents. We've erred on the side of making all information in the release available while also letting everyone know that some features are optional and may not be enabled for their institutions. 

Admins will be able to make copies of the user summaries to distribute to their institution, and the copy may be different than the default version we produce, especially if the admins are not going to enable a feature option or an LTI tool does not apply.

If a feature is not moving to production immediately, can you make a note of that?

With the new release notes format of only having one document, yes, we will identify if a feature is not going to be deployed to the production environment but is staying in the beta environment.  

How urgently should a feature be reviewed? How do we know when beta features are complete?

Terminology confusion—beta can mean one of two things: the status of the feature, or the environment it is in. When we talk about a beta feature, we're talking about the status of the feature. (For the environment definition, see prior question.)

Instructure products are always in a continuous state of update in one form or another—our teams may be overhauling an entire feature or they may be making small label adjustments. Generally, any feature that is announced should be taken urgently right away so our teams can continue to make iterations on the feature if needed, or address any significant concerns that may arise, such as performance behaviors.

Many features in Canvas are in a beta state; feature options are indicated by labels next to the feature's name, but some other features have no indication of its status. Larger projects are usually associated with a priority page in Canvas Studio‌, which indicate the project's full status and goals. In our new release notes structure, we've added a link to any priorities associated with a feature, but we'll make sure to identify the specific status as well so you don't have to click the link to find out how it's going.

However, some smaller features that are deployed to the beta environment may not be associated with a priority, and they may not be associated with further changes at all.

I'll discuss with the product team, however, how we can try to make better status updates for features that may be in the first phase of a change, for instance, so you know more functionality is coming.

Can you note tentative dates for when a beta feature is moving to production?

In most cases, features announced in the beta environment will be available in the production environment as part of the release. In terms of a beta feature that is a feature option, our product team will usually let those be optional for at least three or four releases, depending on feedback from the community. By definition, feature options are meant to be optional and (in most cases) will eventually be enabled for all institutions, so a safe guideline would be to take the feature seriously at least one release after it is initially announced. I'll ask our product team if we can make some modifications for when we know a feature option is never meant to be enforced (which does happen occasionally).

In case of beta features that are significantly and clearly in a beta state (e.g. New Gradebook), we'll continue to focus those in their own user group until the feature is generally available to all customers.

Friends who attended—If I left anything out, please feel free to add an addendum. :smileygrin:

Thanks!

Erin

[jsowalsk]

Thank you!

[erinhmcmillan]

Hi, Linda,

We'd love to say we could do that, but our resources are best served with one video—and then admins only have to manage one video as well for wherever they're embedding it. But we're able to make some improvements! We'll mostly make sure we are grouping features together by user role as much as possible (some features affect all user roles though). The introduction of the video shows what features are being highlighted and where, so users can easily skip through the screencast to a specific part if needed.

We're hoping that the user summary documents will help close the gap between specific user role needs. They won't include all details so they shouldn't be too overwhelming.

Thanks!

Erin

[erinhmcmillan]

Hi, John!

Fixed bugs will be shown in both places. For the video, I just didn't have them showing in the release notes section. No worries! Nothing has changed for that.

Thanks,

Erin

[ken_cooper]

That looks good to me erinhallmark!  Pretty well covers all of what I remember during the discussion yesterday.

Thanks for your write up, nice to have it all in one place.

[ProfessorBeyrer]

erinhallmark Thank You for hosting the live session and sharing these notes. Another example of awesome communication between Instructure and its clients. 

[kburkes]

Will we still get notifications of release notes by email?

[jsowalsk]

erinhallmark‌ will we still get emails about beta and production release notes?

[Chris_Hofer]

 @jsowalsk ‌...

If I'm interpreting the two paragraphs immediately below the section Canvas-Specific Changes correctly, there will only be one set of Release Notes...as it looks like Beta and Production Release Notes will be combined.