Release Notes Redesign notes

Owned by Khalilah Gambrell
Last updated: Feb 09, 2023
4 min read

First Principles

Great release notes for an open-source product should have the following characteristics:

  1. Clarity: Release notes should be written in a clear and concise language, avoiding technical jargon and explaining complex changes in simple terms.

  2. Completeness: Release notes should be complete and cover all the changes, bug fixes, and new features in the release.

  3. Relevance: Release notes should prioritize information that is relevant to the users, highlighting the most important changes and their impact. For each note, it's clear which users will find it most relevant.

  4. Usability: Release notes should be easy to read and navigate, using headings, bullet points, and descriptive labels to organize the information.

  5. Timeliness: Release notes should be published in a timely manner, soon after the release is made available, to keep users informed about the latest developments.

  6. Accessibility: Release notes should be accessible to all users, including those with disabilities, by using accessible text formats and including alternative methods of accessing the information.

  7. Release notes for proprietary services may include detailed descriptions of features and bug fixes, as well as more specific instructions for installation and usage. However, open source release notes should still be clear, concise, and easy to read, while providing enough information for users to make an informed decision before installing the latest version. Additionally, open source release notes may include more links to additional resources, visual aids, or video tutorials to help users upgrade to get up and running quickly.

Meeting notes

 

  • QA recordings very helpful
    • Narration and subtitles 
      • Be helpful for PO and Dev reviews too. 
    • animated gifs
    • need to include in release with context (i.e. link to JIRA or description)
  • Timeliness
    • Release notes - PO contact list and disclaimer 
    • Have Release notes deadline tied to Module release deadline 
  • Release/Developers checklist that includes a task for release notes 


Action items for Feb 23

Meeting notes

 

Where to add link to releases 

  • Consider adding release notes to docs. 
  • Pin slack message regarding releases possibly Slack - general 
  • FOLIO demo 
  • Bugfest too and possibly tie to System information (config file?) 

Next steps for 

  • Review Gloria's survey (1 week deadline) - Gloria
  • Add Release link to wiki page -Michelle (Welcome to the FOLIO Wiki)
  • Pin slack message regarding release - Michelle (Done: added as bookmark instead of pinned, #folio-general channel)
  • Loop in Kristin Martin - KG did on Feb 3rd. Very excited about this effort. 
  • Add what makes good release note documentation - Gloria and Emma
  • Review manual QA recordings to determine if we can include in release notes - Gloria - DONE 


 

Quick Introductions

Overview 

Q1. What is beneficial about our current release notes Morning Glory (R2 2022) Release Notes?

  • Content (plain language) to explain issues
  • Sorted by area of functionality (first table) 
  • Easy to contact the person responsible for each area (easy to sort/group) 

Q2. What is unclear about our current release notes?

  • Not scannable/ Not easy to find things
  • Descriptions are not detailed enough when posting a JIRA link. Need to provide more details. 
  • Comment column is not used
  • Group: What needs to be done before a release upgrade Then another group for during and Then another group for after 
  • Group by functional area
  • added by MF after meeting: hard to find the release notes in the first place, no link on main wiki page https://folio-org.atlassian.net for Nolana release notes
  • added by MF after meeting: for sections that are generated from JIRA issues, like the "Additional Known Issues" section in Nolana release notes, it isn't obvious that only the first 20 (or however many rows) are shown, and if there are more than 20, you have to do another click to see the full list of issues 2.2 - KG made change
  • MF / GG: High level descriptions don't include additional narrative to provide context. For example, "this is a long awaited feature" or "this feature is connected to the bug that was first reported at first date"

Q3. What is missing with our current release notes?

  • A way to engage with release notes? Be able to make a comment / ask a question.
  • Maybe a release Kanban board

Q4. Have you reviewed release notes from other products/companies that you thought did a great job? If, so, please post links. 


Action items for next week

  • Review above responses
  • KG will investigate a Kanban release board 
  • Create quick poll
    • GG: create Google Form
    • EG: Check if Confluence has a way to make better release notes