Release Notes: How to Implement Them in a Fast Delivery Environment
NOTE: do you want to read this article in Italian? It’s here.
When creating software and product documentation, release notes seem easy to implement. Almost a banality.
The truth is that it depends on the environment we’re working on.
There’s a lot of difference between being a Technical Writer in a corporation and a small-sized company, like a startup. Also, there is a great difference between working in an environment where developers release in production once every two months and one where they release every two weeks.
In this article, I’ll show how we can implement release notes in a fast-delivery environment.
Hi I am Federico and I’m a Technical Writer:
Want to collaborate with me? Contact me!
Step 1: say that you exist
The first thing that a software company has to understand is that Technical Writers exist and need to complete their tasks at certain times, exactly as other people in the company. 🙂
If your company decides that developers have to release every two weeks, the release notes have to be ready before the release.
This means that you need all the information you need, you have to test the software (for eventual new features), and you have to have written the documentation before the release.
To do so, the first thing to do is to say to your colleagues that you exist and need some timing, so that you’re inserted in the pipeline and decide with them the process and what you need.
Step 2: decide the process
Now that they know that you exist, you also know that you’ll have strict timings to do your job because the releases are in a short period, so you need to be comfortable with the new features in a very short period.
Anyway, you must establish a process with developers and product, because the release can’t go out if the documentation is not completed.
Ideally, you should implement a process like this one:
- Developers take “y” days to develop new features, fix bugs, and do their stuff.
- Testers take their time to test the software.
- You’re triggered by a scrum master, a project manager, a product owner (or someone on their behalf) that the features are tested so that you can start creating the docs.
- You do your tests, write the docs, and the release notes.
- Someone approves the release notes.
In that scenario, of course, a PM (or who for them) has created a roadmap, so that:
- You presume the features you’ll work on for the next release.
- When devs have completed their tasks, they start with the next release, on a development branch. This way, the timings for the different owners (devs, testers, tech writer) don’t overlap, but the schedule is to release every “x” weeks and this remains the same for the product.
It’s indeed important to have someone who can approve your release notes so that it’s clear that you haven’t misunderstood something. Also, some stuff may remain not publicly available, and this has to be discussed.
A product owner can be a good person to approve the release notes you prepared in a draft. Anyway, take my advice: make the approval process lean and don’t make it rely on only one person. What if the only approver is sick the day they should approve before the release???
Step 3: publish the release notes
Ideally, you should publish the release notes (and all the documentation) together with the product.
This can’t always be done for several reasons, depending on the software you use and many more.
So, the solution is to publish the release notes before the actual software is deployed and write that the new features (and the bug fixed!) will be available in a certain date, in a precise range of hours so that customers know when the software will be updated.
Implementing a release notes process in a fast-delivery environment is not easy, but these ideas will help you set up a process.
Rimember: make the process as lean as possible, with all the checks you need.
If you need help or a consultation on how to implement such a process, contact me.