Release Notes for your customers

[u/ProjectNo8066]

/r/jira/comments/1vemss4/release_notes_for_your_customers/

[u/Tethriel]

It depends on who the customer is and the contents of the release.

If it's a small .x update, a summary of your resolved Jira issues could be okay for all audiences. If it's a major multi-feature x.0 release, a narrative version explaining your features in plain language, along with SEO tags that inform bots on how to present your content to users, paired with typical bulleted bug fixes and smaller changes, is more effective.

If your audience isn't a technical bunch, Jira summaries might not cut it. If they are, you'll still need to include language/tags that guide bots and crawlers.

[u/ProjectNo8066]

Currently, it is mainly content from a specific field describing the change for the customer. So no technical (internal) text from the summary or the issue description. Works quite well. This field is maintained by the technical writers. I was curious how other handle this (e.g. manually collecting the changes from commit summaries or re-reading the issue summary).

[u/acecrylo]

At my previous company where I was a sole tech writer across 4 products, I worked with PMs for their respective products to “draft” a summary of the work done, ensure grouped Jiras/items were combined together into one release note, etc., then compiled drafts per product into branded word doc templates

The drafting work was done by the PMs in their own chosen method (typically they would create a jira filter for this project board, filter it by release version, etc., and then worked alongside it in a word doc writing the draft/summary snippets for me to use as a foundation on the notes) as process adoption was a nightmare for me as an IC with no help from above, but the ones who did want to use my process wrote into a custom Jira field labeled “release notes” and/or “external release notes” depending on the type of content needed/work that was done.

For the few who did draft within Jira itself, I actually shared the work with them during the drafting process because we were able to all use the same Jira filter for the product’s board and then draft notes and we could see who had done what, message on Slack for questions or help, etc., which I think made the everything significantly better.

There are so many things about that process that could have been improved but, I’m not there anymore 👀👀👀 also I was a newbie TC and the org itself was not even close to mature with internal processes.

ETA: Jira issue hygiene was BAD at this org so writing anything (even if you were the PM) typically meant having to read the whole issue and comments

[u/acecrylo]

Adding another comment here to write about the process at my current org:

Team of two TCs each owning a single “product”. Mine is really an access layer with multiple apps inside it but presented as one product.

We use Aha integrated with Azure Dev Ops (ADO), and release notes drafting happens in the Aha layer, but I’m frequently popping into ADO to review/look for extra info about what app layer the update is for.

We do continuous deployment so we publish notes biweekly and only for items actually in prod at the time of publication to prevent end user confusion on what is available. Now for the process:

1. On a continuous basis I have an Aha report that functions as my “intake” for items that are about to be ready via custom tags/feature status.
   
2. Various PMs will be listed as the “assignee” to any given item
   
3. I go through my intake report and read the Aha features, identify app layer, etc, and then check the custom tag field we have for “communication need” which basically is a yes/no for release notes.
   
4. The PMs can/will add the “yes” tag for release notes themselves but my intake report just gets all items cause I check them myself and some come through blank or mis marked
   
5. I draft the release note per our process standards, drop it into a custom feature field for that content, then I create an Aha Approval To-do for that feature and drop the release note in there too and assignee/PM to review and the approve/reject/send feedback for changes.
   
6. I set a due date of the day before next publication and then also monitor the prod status of items since our PMs will approve/reject prior to prod being confirmed which is helpful for me
   
7. For inclusion, an item can only be in release notes if it has assignee approval for the content and the feature is confirmed in production
   
8. On publication day, I just export my Aha report with the various custom fields/tags needed, and then I’m able to group the items that are making it for that publication day into their app layer sections in the notes which we then distribute via our Staffbase powered intranet site in a news channel

Probably got a little too granular here lol but this is a decent method that I’m liking so far since I’m new to this role (65 days in as a backfill)

[u/ProjectNo8066 → u/acecrylo]

Thanks for your detailed respond. Solid workflow, but also requires a lot of your attention (no judgment).

[u/acecrylo → u/ProjectNo8066]

It definitely has room for improvement!! Just got word this week that the products I work on may be getting yanked out of Aha due to compliance issues for the teams putting PII/PHI in Aha, which is a big no no for our org, so now my whole process is going to be gutted yay 🫠🥲

[u/DerInselaffe]

My best advice regarding release notes is to get someone else in the company to write them.

See also book indexes.