CHANGELOG: What I've Learned

Earlier this year, I shared a communication approach I was trying with my team, called a CHANGELOG. I have been applying this approach for the past six months and have learned a few lessons along the way. This post will recap some of these lessons learned, so it may better inform you the benefits and the costs of applying it.

Improved 1:1 Conversations

A primary reason why I started applying the CHANGELOG, was to simplify the routine need of communicating current topics with team members. By channeling this information to a dedicated home, I found this cultivated more unique conversations in the 1:1 sessions. I could then ensure the majority of time was allocated to topics others wanted to cover and allow me to give feedback to their questions. I would still recall things that I would put into the CHANGELOG, especially if I was looking for feedback on one of these news items; however, these were simply reminders and not central points of a discussion. By allowing time for what others want to discuss, it helps me learn more of what is important to others.

The Value of Routine Communication

This year introduced several challenges on maintaining good communication lines with everyone I would typically engage with my work. I found it valuable to proactively ensure I was providing communication on a routine basis. One piece of feedback I received was the overwhelming amount of communication people were already receiving through email. Much of this challenge was the volume or quality of these communications. I wanted to make sure these communications wouldn’t be contributing to this problem. Therefore, I wanted to make sure these were effective and easily digestible.

My approach has been maintaining a central site that hosts a weekly CHANGELOG which gets published every Friday. When I publish these, I would send an email notification that would quickly summarize what content was included for the team to reference. As a result, this would only result in a single weekly email on a consistent schedule (every Friday). The content in the email would focus on highlighting what content is included in the site. Therefore, it was a simple and predictable sized message to indicate what to expect in the CHANGELOG. By proactively providing communication on a consistent schedule, I found that I was ensuring to share content with the team. Furthermore, I would also be checking with my leadership if they wanted to include anything in the CHANGELOG when I knew there could be possible topics may have questions based on recent changes that have occurred.

By having a routine communication that concludes the work week (on a Friday), I found it to be a valuable point to provide a summary of that week. In that brief email that I would send to notify of the published CHANGELOG, I also felt it was important to conclude the email with a message of gratitude. I have often felt that I do not do enough in reminding team members of the impact they have through the work that they do. When you do the work of preparing what all has changed in a single week, you often capture achievements that are occurring through their work. It becomes a perfect opportunity to share that reminder of their impact as it becomes evident when they also see the changes that have occurred in the past week. Sharing gratitude is something we all can do more, and the CHANGELOG has served as a great way for me to do this routinely.

Predictable Format of Content

The format of the CHANGELOG was to make it easy to quickly capture what things have changed from the previous week. To assist in this effort, I try to keep a consistent format that breaks down the weekly events by listing different sections:

• Company: News related to the company, changes being applied throughout the company, or anything that spans beyond our current group.
• Culture: News related to engineering culture of the company. This can include announcements of internal meetups, tech talks, and hackathons. While it is not something that would be at the corporate-level, it is broader than your team and helps to have its own section.
• Group: News related to our current group. This often includes content from presentations that occurred within the group or reminders on requests made across the group.
• Sub-groups: News related to other groups you directly work with.
• External: News that may be highly relevant to the group, but relates to external sources. This may include external conferences, larger tech news related to a product you use, or any other industry related news that you think it would be valuable to share with the team.

Having this consistent format helps in how people capture content from the CHANGELOG. Through these sections, it gives clear categories of what is included and makes it easier to consume in a short period of time. By applying it in the same format each time, it makes it easier to follow and navigate. Consistency can help those who are consuming the content, which is an important consideration as you are wanting this to be an easy, accessible set of information.

The Historical Inventory

When first introducing this topic with other team members, several thought of it as a newsletter. However, I felt it had some distinct differences to newsletters that I had experienced before. One apparent difference to me, was having a central site that hosts all of this content for each week, versus all of the content living in an email that is sent out on some schedule. When newer team members would join, they would have the full inventory of past CHANGELOGs to reference. Previously, it would require forwarding them all these past emails to obtain this same content. Furthermore, these were easier to share with others outside of our group. I found others referencing the CHANGELOG which weren’t even in our group, therefore expanding its value simply by reaching more people without me managing who was on the mailing list for the newsletter. Lastly, I would re-reference past CHANGELOGs when it had relevant information which helped remind people where they could go to find this same information themselves. If I forwarded them an email to share this information, I would be training them to ask me again to see if I could recall some past content from my inbox (which of course is not that helpful). By having it in an open, searchable inventory of content, they could explore on their own without requiring anyone else to find this information of the past. The historical inventory becomes the asset you can to continue to leverage after you initially share these updates.

It Takes Time

To prepare this content, it takes more than just a few extra minutes. I found that I typically spend over an hour preparing each weekly CHANGELOG. Each addition into the CHANGELOG doesn’t take too much time, but some require more content included so the single reference has all the relevant links. Some information gets shared with me as an email, that I then want to make sure is part of the CHANGELOG. I export these as PDFs and include them in the site as the reference to the single CHANGELOG entry that mentions it. Collecting and inventorying this content takes additional time, and those minutes add up when you build these each week.

Conclusion

After doing this for 32 weeks, I have found that this has been a beneficial communication tool. Each time I have referenced a past weekly CHANGELOG, I know I’m getting more value out of what was previously shared. This has required more effort than what I had originally expected; however, I believe this has reduced the total amount of time I would have otherwise invested when trying to further communicate this same information throughout all my existing 1:1 meetings. Lastly, I think this year was an important moment for me to continually try different things to proactively communicate on a routine basis. Rather than creating yet more things to read, I wanted to create more concise communication that was valuable to periodically receive and easily digestible for my team members.

While it has required additional effort to keep it as a routine communication to the team, it has been something that becomes a reliable form of staying in touch. I hope these lessons learned are helpful in your journey in improving communication within your organizations 😀