6 things to consider when releasing product documentation

Whether you are interested in the technical writing field or just curious about the day-to-day life of a technical writer during the release of a product, this is the post for you.

Here I’ll show you the challenges that I went through to properly release documentation for Feedzai’s fraud detection product.

The process of releasing documentation can be overwhelming, as there is a lot of information to absorb in a short time period. Nevertheless, with proper planning and support from the engineering team, it is actually possible to achieve this milestone almost smoothly.

There’s no doubt each release has different circumstances, and in this specific case, I sought advice from a more experienced colleague. I want to share this advice with you.

Allocate enough time for the release (especially if it’s your first time creating such extensive documentation)

When I began this journey, I was told it would be wise to schedule two weeks to prepare for the documentation release. This period was not meant to perform the release itself but to do the following tasks:

• Write the release notes.
• Prepare the “Relevant Changes” page, which is a list of changes that administrators need to consider after migrating from an older version to the new version.
• Perform test tasks for the release.

The suggestion to allocate two weeks came from a colleague experienced with this same process. Without her advice and support, I would have needed much more than two weeks. It’s not like guidelines weren’t available, but it’s much easier when someone tells you what you should read (cheater!). Also, all the unexpected challenges and error messages that popped up would have completely swamped me if it wasn’t for a second pair of eyes.

Plan your tasks ahead

To better plan my tasks, I listed the new and changed pages that came up during the quarter and shared the list with the product manager. Product managers are responsible for ensuring that content is valid for release. Additionally, I went through a release checklist, which is a page that contains all the necessary steps for a documentation release. This way, I was able to better plan my time for each task and make sure that everything was closed on time.

Talk to the people you depend on

As the release date approaches, unexpected change requests may come up. For instance, the need for changes to the code may only be discovered in the last development sprints. For that reason, it was crucial that I talked to the people who were working on those changes. If I wasn’t sure who they were, I’d ask the product manager.

I confess that I have always disliked chasing colleagues to get the information I need, especially when everything’s on fire. Sadly for me, this is part of my job. Don’t get me wrong, I enjoy what I do, but I can’t get rid of that constant-poking-on-people’s-shoulders feeling.

After finding out who held the important information, I’d ask questions. Questions are crucial for this job. But for a newbie like myself, I wasn’t even sure what questions to ask. I guess it takes time and experience. I know, this is not the answer I’d want to hear either. But since I lacked both experience and time, asking all the questions that popped into my head was the best way to go. At companies like Feedzai, funny questions [not the ones that make you laugh, but the odd ones] are welcome, mainly because we are encouraged to invest in one another. By turning a newbie into an expert, our lives become easier. As a consequence, the company grows.

My experience has taught me to be proactive. If I didn’t know what to document, then I would schedule meetings. I struggled not to be affected by the development team’s unavailability, as letting this affect me could prevent me from doing my job. Subsequently, I noticed that they were quite willing to support my work.

Write the release notes in a timely manner

Argh… Release notes… Well, release notes are brief introductions to the new features. The information I needed to produce release notes was stated in the new pages. The hardest part isn’t the writing process; it’s becoming a ping-pong ball during the review process. These notes must be approved by other team members such as product managers, marketing directors, product managers again, and the product director.

As expected, due to the number of people involved in the approval process, these notes went through a lot of changes, and if I wasn’t careful enough (heads-up, I wasn’t) discussions would continue on the day of the release. This can negatively impact the documentation release, especially because I needed to handle other release-related tasks, which didn’t revolve around release notes.

Close your tasks before the release

Before releasing the documentation, I made sure all open tasks in my planning and checklist were closed. This is why keeping track of all content is so important; tracking ensures that nothing gets lost or forgotten.

Release the documentation

On the day of the release, I was mainly focused on the process of releasing the documentation. By putting into practice the tasks I had previously tested, I was able to go through the steps without major issues.

At last, release accomplished! Now gather your team and go grab a beer!

Not so fast!…

As I mentioned in step 4, I was not careful enough. The release notes were still under iterations by the end of the release day’s working hours. And this was the main issue I found in this product’s documentation. If the release notes aren’t closed, I can’t close the documentation either. In this case one page called What’s new needed to contain the exact same information as the release notes. Fortunately, everything was approved on the official release day. The documentation was released, this time for good!

Final thoughts

Overall, the process of releasing Feedzai’s data science product documentation was positive. The clusters were supportive and interested in delivering quality content.

The most significant stepping stone, though, was the release notes’ chain of approvals, which despite being established, is not formally driven. By that, I mean that a system of approvals should be implemented in a way that each member can review the content, provide feedback, and approve the documentation before we miss and have to extend the deadline. From my experience, releasing documentation requires organization, knowledge about the product (to some degree), and previous involvement in the clusters. Sure, my life would have been easier if I had previous contact with each team or if I knew more about this product. But as I mentioned above, it’s about asking the wrong questions in order to start asking the right questions. Just accept that this won’t come easily.