What did you do at work today? How about last week? I spent a couple of days in quarterly business reviews, and wrapped up yearly planning activities for AWS Data Exchange and AWS Marketplace. I also added some unit tests to a project that I am onboarding into.
Since my first day in AWS, just over a year ago, I’ve been experimenting with keeping a CHANGELOG of everything I do, available for everyone at the company to see. I think you should too!
Keeping track of humanly readable changes in the open-source world has been a long established best practice. It shows that maintainers truly care about customers - making it accessible and easy to understand the changes across multiple releases. As a user, I can find out how changes will affect my application when upgrading, without having to engage a human. I can track down a regression, or an improvement. CHANGELOGs promote transparency, improve clarity and, in the long run, increase trust in the work of others.
My customers are AWS customers, but also developers and managers that I work with. Keeping a CHANGELOG has helped me earn their trust. In general, earning trust is one of the most challenging things to do. Trust is slowly won, and quickly lost. Earning trust is uniquely difficult in more senior engineering roles, as the scope of your work grows, the nature of the work becomes more independent, and results are often delivered over longer timeframes.
So far, keeping a personal CHANGELOG has had several clear benefits.
-
My 1:1s have gotten to be a lot more productive. All my 1:1s, including with my manager, begin by having them read my CHANGELOG since our last 1:1. This gives them the opportunity to quickly gather context, immediately see what I have been working on, understand what’s going on in my world, and quickly get to more meaty conversations.
-
My CHANGELOG helped a lot of new Engineers joining the organization. Many have said that my early CHANGELOG entries were helpful to understand what one actually does during their first weeks at Amazon. For example, I spent a huge amount of hours in training, set up a laptop backup drive, and made my first non-trivial code change during week 2.
-
My CHANGELOG serves as a personal wiki and reference. I often need to refer to an existing document, person or conversation. Remember reading a document last week? I know exactly where to find that link!
-
My CHANGELOG serves as an internal motivator. It helps me to be honest with myself, and gives me data that helps me reflect on how much busy work I do vs. “actual” work and teaches me where and how I can learn and improve.
So how do I actually keep a CHANGELOG? I keep a yellow sticky note to which I add items during the week, then copy-paste it into a Wiki every Monday. I always pay attention not to include any confidential information, such as names of candidates interviewing with AWS or referring to customers.
If you start a CHANGELOG, tell me about it!
Finally, here’s some Ruby to generate a TOC till EOY.
require 'date'
start_date = Date.today
end_date = Date.new(Date.today.year, 12, 31)
(start_date..end_date).select(&:monday?).reverse.each do |dt|
puts "* [[#{dt}]]"
end