A while ago I came across a post on LinkedIn that talked about how change logs should be done in the context of CI/CD. In other words: How do I handle this topic when software is being delivered frequently?
The question was originally asked from the perspective of a freelance developer, who often worked on multiple projects. This setup also implies that the developer can be on and off the same project, depending on its priority relative to other work at the same client, or simply for budget reasons. This uncertainty about personal availability to other project members at some point in the future, is certainly a factor that makes this a bit more pressing than for regular staff.
The post basically recommends to think about the target audience for the release notes. Marketing will certainly want something very different from 3rd-level support, regular users, or fellow developers. So how do I manage to address all those needs with a single document?
I don’t.
Create one release notes document per target group
In many other situations the “one size fits all” approach has long been gone. Why not do the same for release notes? We already have installation instructions separate from user guides, operations manuals, and many others documents.
The same goes for a sales context. Here we use the concept of buying personas to make sure that a CIO gets the relevant messages, just like an engineering manager or developer. So isn’t it obvious that the same idea would be useful for release notes as well?
The counter argument will likely be effort. But didn’t we have that discussion for testing as well? Automation is, once again, the key factor. So let’s look into this in a bit more detail.
Leverage existing data
At least in my past the effort for providing release notes to whatever target audience, came largely from the fact that I had to write those notes. You will now say: Of course you had to write them, they were not sent over from the universe. But what if we could create them in an automated fashion?
A large amount of the information should already be available in some semi-structured form. Or are you telling me that you do not create something like user stories (or similar), tickets with problem and solution summary, etc.? Yes, we can probably not use them in exactly the state they are in today. But the additional effort is limited and will largely be a one-off exercise.
In a nutshell we need to find a way that allows us to go over the existing systems and data and extract what is needed. The latter needs to happen for each target group. We generally find that each change falls into one of the following categories:
- Change is relevant for all groups and they all need the same information.
- Change is relevant for all groups but they need different information.
- Change is relevant for some groups and they all need the same information.
- Change is relevant for some groups and they all need different information.
- Change is relevant for none of the target groups.
- (Change is relevant for nobody.)
What do we make out of this? Overall we are looking at basically two areas in your existing systems and processes that need adjustment. We need to able to determine whether a change is relevant at all (or not) for a certain group. And if it is relevant, we need to retrieve the information that make sense for this group.
Rough idea for implemetation
From an implementation point of view you need to first identify the issues/tickets, wiki entries, etc. that are relevant for a certain change. The second step is then to determine which groups need to know about this change. A good example for something that is probably relevant for no release notes at all, is the change of a variable or class name. But hang on: Doesn’t the development team deserver their own release notes? (In general I think the answer is yes.)
The third step is to extract the relevant information for the target group. That can basically be achieved in two ways. Either you have a separate “field” per group and enter things there. Or you have a common field but mark parts of it per target group. Something like this (in Markdown of sorts):
# Overview {{group=all}}
This is our new feature ...
{{group=operations}}
We solved a big pain for our ops colleagues.
{{group=marketing}}
This differentiates us from the competition like ...
## Benefit {{group=user,marketing}}
You can now do ...
## Upgrade {{group=operations}}
A new database index was created
## Upgrade {{group=user}}
You will need to do this
## FAQ {{group=user,operations,support}}
- How can I do ...
This is not exhaustive but should give you an idea.
Other ideas would be to somehow incorporate regular documentation. A new feature should be reflected not only in the release notes but also the user manual, perhaps the installation guide etc. Adding links to the relevant sections in those documents (and not simply the document as a whole) would also be helpful.
But we are now moving into the direction of documentation management as a whole. It is an interesting topic in my view, but would lead too far for this post.
If you want me to write about other aspects of this topic, please leave a comment or send an email to info@jahntech.com. The same applies if you want to talk how we at JahnTech can help you with your project.
© 2024 by Christoph Jahn. No unauthorized use or distribution permitted.
