Release Notes are Crucial!
For many companies, release notes are the most frequent form of customer-directed communication.
So why do we treat these notes like an obligation? Companies spend too much time and money on an inefficient process rather than taking advantage of a great opportunity.
At easyDITA, we think there’s a better way. We’ve developed an improved release notes process within easyDITA. One that makes the process and the output customer-centric while opening the door for companies to finally engage at the next level.
Watch the webinar below as Jarod Sickler takes us through the current shortcomings of many release notes processes. See how easyDITA manages to deliver personalized release notes to our customers while reducing effort by 70%.
Additional Webinar Questions and Answers
During this webinar, attendees asked a number of excellent questions. Some were answered at the end of the webinar. Unfortunately, there simply wasn’t enough time to get to all the questions. Below you can see answers to the questions that we were not able to answer during the webinar.
Do you generate new filters in Jira for every release note?
No, we don’t generate new filters. Through trial and error, we’ve zeroed in on the Jira filters that seem to suit our needs for now. Of course, I’m constantly evaluating whether that process should be updated or changed. But for now, the filters we have in Jira are working well.
What is a good way to organize the topics of a release note?
That’s a great question, and it’s one I think is dependent on what your release notes are about and the types of products you are documenting. For us, it makes sense to break down our release notes by software components, and then further into Fixed, Enhanced, and Added categories within each component. I think that gives readers a straightforward way to find what they’re after quickly, get the information, and then move on to other issues.
What should be the order of the TOC?
When I build the release notes, I ask myself, “What’s the most intuitive way a user would approach our software?” In essence, I’m trying to get in the mind of a typical user and what interfaces they would encounter first. I start building the TOC based off my answer to that question. Along with that, I try to prioritize interfaces and release notes based on how heavily used those interfaces are. For example, I like to prioritize any issues related to our topic editor and content library since those are the two main interfaces our customers interact with.
What happens if there are changes after you’ve generated the RNs?
That’s the beauty of DITA. If there are changes to our product that need to be reflected in the release notes, I go to our content repository, update the release notes source (DITA) files and then simply republish the release notes. DITA makes it possible for me to update files in one location and then push all those changes to our various output formats.
How frequently do you publish release notes and how many release notes do you publish in a given cycle?
Up to now, we’ve only created release notes for major release versions and when customers ask for them for particular maintenance cycles. However, I am planning to update our release notes cycle to include quarterly release notes that are system-wide, along with our regular customer-specific sets when requested. My preference would be to generate release notes at least monthly, regardless of our official release cycle. That way I would be able to compile release notes on the fly even faster! At this point, I don’t pay close attention to the actual number of release notes in a given cycle. I focus on the severity level of the bug fixes, enhancements, and new features. I include notes for any major issues that I know customers are expecting or would be excited about.
Where does the integration come into your process? Or is it external to easyDITA?
By integration, do you mean an easyDITA integration with JIRA? We don’t have an integration with JIRA. We just output an XML file of the issues we want for our release notes.
If you mean something more along the lines of using this process outside of easyDITA, then I’d say that in principle it’s possible. At this point, we developed this process specifically in our system and it’s all we use. But, again, it’s in principle possible that this process can work in any DITA system. It’s DITA that’s the key, not easyDITA here.
We created the configuration files and wrote the XQuery report that converts the JIRA items into DITA content, but that’s really a fairly straightforward process if someone wanted to do it in another DITA system.
What specifically do you mean by “curate”?
First, I love this question. These are the kinds of questions that often go unasked but are very important. By “curated” all I mean is rewritten from “dev-speak” into language that our end-users can understand and use. It’s not uncommon for me to come across a JIRA item with a description like, “L10N endpoint doesn’t work,” which is entirely unhelpful to our end-users, and honestly even to me. But I use the JIRA issue description as the release note for my end-users. So, I rewrite (curate) those to make them usable.
Slack itself is a messenger and is used by many end users. So it’s justified when they have interactive release notes. How interactive would you suggest for one to get, in the release notes if the company is more focused to serve enterprises? The target audience would be highly technical and not as cool as Slack target audience. Can you please help with this?
This is a good question. Our software is an enterprise-level solution. So this is a question I regularly deal with when I’m generating release notes. My general approach is to a.) make sure I offer the helpful technical details our users want and need, and then b.) if I can squeeze in a quick and appropriate joke, I do.
I won’t make a joke in each note, but I try to pepper them in, if possible.
Do you use one topic per Jira item?
Yes, and no. 🙂 We create “warehouse” topics for each Jira item. The item details from those we reference in the actual release notes. For our public-facing release notes, we group similar Jira items into topics, and these tend to be longer topics, depending on how much content we reference from the warehouse files.
The focus on release notes appears to have high value for product