Release notes

[amyjko]

What's the problem?

We currently manually describe changes to each version in our CHANGELOG file, and occasionally in official releases, but we do not communicate updates in the app itself, meaning that fixes and new features go unnoticed.

What's the design idea?

Create a place in the application to summarize localized release notes in a way that creators will understand.

Who benefits?

All creators committed to the platform.

Design specification

(This section should be included after a design proposal is ready and approved, and the buildable tag is added. This text can remain until then. Designers should add their proposal here, not in a comment).

Draft 1

Solution I added a subheading to the Homepage titled 'Updates.'
For logged-in users they will get a pop-up at the top of their screen whenever there is a new patch note. The update notification is at the top for logged-in users because it's one of the first things users will see when opening the app. The popup is designed to alert you about changes in the app that you should be aware of. Placing it above the logo temporarily emphasizes its importance over the usual branding. Logged-in users can dismiss it if they don't want to see it. Logged-in users also have context about how they normally use the app and features. They can better understand how the changes impact their existing workflows.
For non-logged-in users, there is no pop-up at the top of their screen. I wanted the update notification to be relevant and useful. Having the notification for all users, including first-time visitors, could be disruptive and confusing if they're not already familiar with the app. We want the first experience to be clean and focused.

Left: Not Logged-In Homepage | Right: Logged-In Homepage

When users click on the 'Updates' subheading, it leads them to the 'Updates' page. This page is a high-level look over all the patch notes released. Teachers can look up keywords to determine if that keyword is in any of the patch notes. This allows them to easily search for updates regarding the topics they teach to their students.

Users can then click on the patch note, which will redirect them to the page specifically for that patch note. Teachers can read what changes have been made to that specific function so they can relay that information to their students. In that patch notes page, there will be an easy-to read summary about what changed, and maybe even some pictures (before and after) or gifs showing how to use any new functions.

• Yes, there would be a particular organization, which was not properly conveyed in the prototypes. It would match the CHANGELOG where "Added" updates would be shown first, then "Fixed" updates, and finally "Maintenance" updates.

  Would we localize these, or would they be English only?

• Yes, these would be localized so non-English speakers can understand updates to Wordplay

[jasoncabusao]

Hi! I'd like to work on this issue.

[amyjko]

Yay! I look forward to the design proposal @jasoncabusao.

[jasoncabusao]

Hi @amyjko!

Here are the questions for the user interviews that I was going to conduct on current Wordplay users and teachers. You mentioned in class that I could send you the questions and you would be able to provide me some insight, so here they are below!

Awareness: How do you currently stay informed about updates and changes to the Wordplay platform? Have you ever missed or overlooked an update or new feature release? If so, why do you think that happened?

Preferences and Habits: What channels or sources do you prefer to receive information about updates or new features? How frequently would you like to be notified about updates or changes?

Understanding and Clarity: How important is it for you to understand the changes or updates being made to the platform? In what situations would you want to learn more details about an update? Are you aware of the Change Log on GitHub. Have you ever encountered difficulty understanding the descriptions provided in the Change Log file or release notes? What additional information would be helpful for you to better understand updates or changes? How much technical detail about updates do you need? Is developer-focused language clear?

Impact on Workflow: How do updates or changes to the Wordplay platform affect your workflow or usage of the application? Have you ever experienced issues or challenges due to not being aware of a particular update or bug fix?

Integration with the Application: Would you prefer to receive notifications directly within the application (popups, or designated sections), or through email, push notifications, etc.? How would you feel about having a dedicated section within the Wordplay application for viewing update summaries or release notes? What features or functionalities would you expect from such a section? What words would you look for when trying to access new features, updates, or bug fixes.

Feedback and Suggestions: Do you have any suggestions or ideas for how we could improve the communication of updates and changes to creators on the Wordplay platform? Is there anything else you would like to add regarding this topic?

Let me know if you need any more clarification, or if I should alter anything!!

[amyjko]

Great questions!

First, I'll answer them as I think teachers would answer them, even though these are hypothetical scenarios that we're imagining:

Teachers

• I suspect teachers will want to know about any changes that would affect their lesson plans, examples, etc. That would include changes to the programming language, removed features, major redesigns. Knowing about new features will probably be helpful, but less so, since teachers often don't have a lot of capacity to learn new things right away. The bottom line is that they need to know how changes will impact their teaching.

• Teachers get immense volumes of emails; I highly doubt they would want notifications. I suspect the best notification place would be in the interface itself, so they learn about changes in context when they're doing prep work. Super users might eventually want notifications, but that's not a use case worth designing for now. Teachers are our priority.

• There is zero chance that a teacher will read the CHANGELOG, unless they are an experienced software developer. We're not designing for those teachers :) We should definitely not write release notes using developer-focused language. They are not developers.

Students

• The students we're designing for will have projects in and potentially out of class. I suspect they'll be far more focused on new functionality that enables them to express new things. Teachers will care about this too, just in service of students, and future prep.

• We cannot contact students via any notification channel because of COPA, so updates would have to be in-app.

--

Finally, one comment on the questions. They do a great job exploring a wide breadth of concerns. But there are so many and they overlap so much. Before I'd ever send such questions to a teacher, I'd expect you to severely edit them down to the most essential things, and ask them in terms of teaching needs, not in terms features or notification channels.

[jasoncabusao]

Hey Amy! Just updated the issue to include my design proposal! Let me know if you have any concerns.

[amyjko]

Great iteration! I like the general structure you've laid out. More design questions:

• Why is the popup at the top of the page? (Is it more important than the name of the site, for example?)
• Why show the pop up for only logged in users? (Always in include design rationale in your designs, not just what but also why).
• How would these be organized? The sketch has "Added", but would there be particular organization, like CHANGELOG, or just an open blog format? Would bug fixes be listed, or just new features?
• Would we localize these, or would they be English only?

[jasoncabusao]

Hi @amyjko, thank you for the design questions. I updated the issue to address your concerns. Let me know if you have any other lingering questions!

[amyjko]

Thanks @jasoncabusao. More feedback:

• Integrate the rationale in your design specification, not as an addendum. (You want readers to understand the rationale for each decision right after you explain the decision; if you separate it, as you have, it's much harder to read and understand).

• You've indicated that there will be organization, but not precisely what the organization is. Remember: designers decide exactly what we're building, developers build it. Add the exact details of how you're proposing we organize the updates.

• If the goal is to get logged in users attention, I'm not sure the home page is the best or only place to do that. They're also likely to be on the projects page, on a specific project, on their profile page. Why not place the updates in the persistent footer, which is visible nearly everywhere?

• If you're proposing we localize every update, what process would we use to do that? Would we delay a release until we'd localized it in every language? Would we have a new part of the localization team that coordinates around updates? Would we use machine translation and just hope for the best?

[amyjko]

It's the end of Winter! Please provide an update on this issue, including:

• Whether you plan to continue work on it
• If you do not, 1) provide a detailed update of its status, 2) add any unfinished work, 3) list any any unmerged branches, and 4) unassign yourself, so someone else can take over the task. Please leave the issue in better shape than you found it, helping future contributors to start from where you left off.

If you do plan to continue work on it, carry on. Otherwise, thank you for your contributions!

[amyjko]

No reply :( Unassigning @jasoncabusao @coysmax.