A few months ago, I started working as a frontend dev remotely full time for the first time. I guess I’m not the only one due to COVID-19. I was reading a lot about how communication is hard in remote teams, so I was thinking about what I can do to improve how I communicate with my team. I came to this experiment of making animated GIFs of each feature I’ll implement and using it in the pull request (PR) description. After a few months, I must say I’m very happy with the outcomes and I’ll definitely keep doing this. In this blog post, I’d like to share some insights from this experiment.
At first, it felt pretty daunting to even make a single GIF. I must admit that making the first one took me at least one hour, probably more. That involved trying out a couple of apps for screen recording. I can save you some of that time by recommending an app called Peek if you’re on Linux. It has a super simple UI for selecting a part of your screen you want to record and a keyboard shortcut to start and stop recording. If you’re not using Linux, you can use LiceCap on Windows or macOS. I had to do the recording multiple times before I got a recording with no misclicks and other unwanted events.
The beginnings were hard but definitely worth it. These days it often takes me less than a minute to record the GIF. But why am I so excited about making the GIFs?
Why animated GIFs?
Before I go into the benefits, let’s see why I do not use some other format.
It would definitely be simpler to make a static screen-shot. It might be specific to the types of projects I’m working on, but in my experience, over 90% of my PRs involve some interaction. The interaction usually cannot be easily made obvious from one (or even more) static screen-shots.
Another option I quickly dismissed was to make a video. The problem is that video cannot be integrated into the description of a GitHub PR (or comments).
No more “What I see is not what the reviewer sees”
It happened to me countless times in the past. I submit a PR, ask for a review and the reviewer complains about some part of the UI looking weird while I thought everything looked good. Sometimes it took even a few back and forth messages to find out that it looks different on the reviewer’s machine. The root cause was usually some divergence between my and the reviewer’s machine. It might have been some dependency, a different browser, or something else. No matter what the root cause is, you won’t get into this situation in the first place if your PR contains a GIF of the feature.
No more asking for review on a broken feature
This happened to me both on the reviewee as well as the reviewer side of the review process. The feature was basically ready for review, I tested everything, all good. Then I just did one more small tweak of something and submitted the PR for review only to find out later that almost nothing of the feature worked for the reviewer. This just won’t happen, if the last thing I do before submitting a PR for review is to record the GIF of how it works.
User point of view testing of the feature
In some cases during a recording, I realised that the feature wasn’t working as smoothly as I thought. Then I went back to coding to eliminate some extra clicks or other clumsy behaviour. Afterwards, it was so obvious that I couldn’t believe why I had developed it more complicated in the first place. I think that this is because you’re looking at things through different lenses when developing. Just by changing the user’s lenses, you can see the product in a different light.
Easy to check what did it look like in given PR weeks or months later
It doesn’t happen every day, but sometimes I wanted to show someone what some feature looks like, or what it looked like a few months ago. I can always checkout to a particular point in the git history, but it’s so much easier and faster to look for it through your past PRs.
More visibility, more feedback for your work
Last but not least, visuals make your work more visible, just like in your social media posts (see some random articles about it). If you have something like the GitHub – Slack integration set up in your organisation, people are watching what is going on. The stream of GitHub events in Slack can be overwhelming and sometimes impossible to follow 100%, but I can guarantee you that an event with an attached image will get more attention than some cryptic text. Thanks to that I receive some improvement suggestions here and there. Or some positive emoji reaction, which is always a nice thing to receive.
Conclusion
I’m most likely biased here, but I can’t help myself from being convinced that recording animated GIFs is great and you should definitely give it a try. It might take some extra time at first, but it’s totally worth it.