How to Talk About Software Changes

My go-to four-point outline for demoing my work

Photo by Headway on Unsplash

So you wrote some code. Now what?

Inevitably you’re going to end up improving upon someone else’s work. How can you celebrate your improvements without offending the original authors? How do you foster a culture wherein others feel invited to improve on your work in the future?

The following is my go-to four-point outline for demoing my work. Granted, any presentation is going to be subtly different, but this is a good starting point to riff on:

1. What was the previous state of things?
2. Why was it insufficient?
3. What did we change?
4. What do we anticipate being better?

Let’s break down each step.

1. What was the previous state of things?

Photo by Aron Visuals on Unsplash

Frame the problem domain. Especially in a larger organization, not everyone will know about the area of the product that you changed. This works better as you know your audience better. If you’re presenting primarily to long-tenured employees, you can get away with something as simple as “We made some changes to the checkout page.” When presenting to primarily new employees or folks new to the product, don’t be afraid to get more into the weeds.

For folks very familiar with the problem domain, this might be a single sentence: “This morning I’m going to show you a change we made to the checkout page.” For another audience, you might need to explain the background a little bit more. Use your best judgment.

2. Why was it insufficient?

Part of software engineering is the role of “software archeology” — digging through layers to understand how the project came to be, what the thought process was at the time, and how that history has evolved (and been forgotten) over time.