Standing out: Three daily work ethics that will set you apart
Improve daily with these three simple habits
If you’re new to this newsletter, welcome 👋. My name is Zak, and I’m on a mission to discover what makes a high-value engineer. If you enjoy this content, perhaps you might consider subscribing to this newsletter. I release an article every Tuesday, and I aim to increase my content output in the future. Your subscription is a sign of your support and is greatly appreciated. Thank you. 🙏
I firmly believe that doing the little things right over and over contributes to our success as engineers. Whilst we do experience opportunities in our careers that we would consider to be “big” moments, the success of these moments hinges on how attentive we are to the daily details. In this article, I will share with you three ethics I perform daily to improve as a developer.
Read time: 10 minutes
Ethic #1: Avoid description-less pull requests
There is something unsettling about a PR that lacks a description. For as long as I can remember, in my career, I have always added a description to my PRs. Even a change as trivial as updating a README.md file gets a description. Perhaps it is due in part to my early days in the industry as a tester, a role that required clear communication with the engineers when I found an issue with their code. This habit of adding a description to every PR has served me well, and I will share with you how I construct my PRs, but first, we need to address the matter at hand: why is the absence of a description problematic?
The sins of a blank PR description
First, and perhaps the most obvious problem of a description-less PR is such a PR is devoid of any rationale explaining the code change. Sure, you might be able to encode this rationale into the PR’s title, but typically, the title describes what the change is, not why the change exists. The description is the place for the why. At the time of writing the PR, you and perhaps the team reviewing it, might be well aware of the why already, but can you be so sure you’ll be able to recall the reasoning six months from now? What about during an incident when the pressure is on to produce a fix? Critically, a code change with a nebulous provenance doesn’t just impact your future colleagues, it impacts the future you, too.
Be kind to your colleagues and your future self: write a description.
The second reason PRs need a description is that it demonstrates to the reviewer that the author has considered the code they have submitted—a degree of quality assurance has been taken. My faith in that engineer increases when I see a PR with a fleshed-out description. That engineer has taken the time to consider the code change, why certain decisions were made, and anything else I should be aware of as the reviewer.
The final reason I have a personal aversion to description-less PRs is that, at best, it demonstrates laziness on the author’s part, but at worst, it’s downright rude. When you submit a PR, you’re asking your colleagues to spend their time reading through your changes, supplying feedback, and eventually offering their approval. This is not an inexpensive transaction, and whilst, yes, as engineers, we are, of course, expected to review code changes, we also have to be selective about how many PRs we review and the priority of each. If I’m going through a busy period at work, and you ask me to review your PR, but you don’t even bother to spend two minutes writing a description, then why should I spend twenty minutes reviewing it?
Make the decision to review your work an easy choice for your colleagues. This is particularly important when operating within larger engineering teams. In my current company, we have a culture of reviewing PRs that come from outside our immediate squads. I love this because it encourages cross-team collaboration. It’s particularly beneficial for new joiners who need exposure to various parts of the system. But this method adds an extra (healthy) burden of responsibility on engineers submitting code: you have to assume someone outside of your squad, with no context of the problem you are addressing, may review your code. The importance of offering that person some context around your change is hard to overstate.
And, in the interest of completeness, no: linking the JIRA ticket to the PR doesn’t count as a suitable description. PRs are not always directly related to the requirement in the ticket. If anything, leaning solely on the connection between the JIRA ticket and PR will add more confusion to the situation.
Example
With that out of the way, let me share how I construct PRs. A picture is worth a thousand words, so I can only imagine what a GIF is worth. I’ve created an imaginary code change where I’ve built the Divider option in the Substack dashboard:
Notice that there isn’t much to one of my PRs. I don’t write for the sake of writing. I consider what needs to be shared as part of the description, and I draw the line at that. It’s important to exercise brevity in your descriptions—again, make it easy for your audience to start reviewing your code as quickly as possible. Don’t give them a short novel to digest. It can be tempting to produce a PR template with all manner of fields, checkboxes, you name it. In my experience, the more you try to generalise PRs, the less relevant such fields become. Keep it simple.
I wouldn’t recommend all of these components to every PR you write; it will depend on what your change is. As a frontend developer, naturally, a lot of my code changes result in a visual output. Such changes are more amenable to being captured as a GIF or short movie. If, perhaps, you work predominantly towards the backend of the stack, then an image of the change might be less relevant.
Stretch goal
If you want to make your PRs even more reviewer-friendly, I recommend, prior to submitting a PR, performing a self-review of your code. This requires you to detach from the code you have written and look at it as though you hadn’t written it. Leave comments on the PR like you would for someone else’s work, and highlight areas of code that warrant your reviewer’s attention.
Ethic #2: Use audio and visual recordings when communicating complex ideas
A previous company I worked for had a subscription to the screen recording service Loom. The tool is pretty simple: it makes it easy to record your screen and record yourself and allows you to store the recordings on their cloud. My employer had a free subscription lying around that had been used once or twice by the sales team. As an engineer, I saw an opportunity with this tool. My line manager at this employer was the de facto product owner and also a co-founder (this was a small start-up). Naturally, getting any of his time was challenging, but I saw Loom as an obvious solution to this problem. Now I could record a three-minute video showing off some feature or issue, and he’d get back to me later. Perfect.
I began using the tool more and more, not just for videos to my manager but content for the rest of the company, whether demonstrating features or showing off findings around a particular bug. The benefit I enjoyed the most from using this technology was getting through a demo without interruption.
Perhaps you’re working at a company where you could see similar value in such a tool. However, if not, then you might consider using screen recording software simply to improve your communication quality with other colleagues. This is how I’m using such software in my current role. My employer is far from a start-up: the product is established, and the tasks are well-defined, so the amount of communication around a feature is not warranted. But when it comes to talking with colleagues, the benefits of such a tool are massive. In ninety-five per cent of cases, I can effectively communicate with colleagues using text. However, there exists those five per cent of situations where I begin writing a message, and before I know it, it’s turned into a long-winded, convoluted mess. It’s during these moments that I know a video message would be more appropriate.
I have received nothing but great feedback when I’ve sent a colleague a screen recording explaining some issue or asking a question. Even a simple audio message is appreciated. If you’re looking to make an impression in a new job, creating content like this will likely do just that. So many of my former engineering colleagues avoided communicating this way.
Example
Let me demonstrate this approach with an example. Following on from the fictitious example PR above that introduced the Divider tool in Substack, in this video, I walk a fictitious stakeholder (Matt) through an issue he has experienced when testing the tool:
Keep it short and sweet; your audience’s time is precious.
Stretch goal
When creating a video recording, record your face. When the camera is rolling, this can force you to focus even more on the quality of the recording’s output.
Ethic #3: Communicate with conviction
This final ethic attempts to break a common habit amongst not only engineers but people generally: a lack of conviction in one’s writing. This can be detrimental to your perceived authority. If colleagues cannot get a straight answer out of you then they’ll stop coming to you. This is particularly relevant to us engineers as we are often closest to the underlying tech, and so find ourselves faced with questions from various stakeholders. This, unfortunately, presents plenty of opportunities to practice this poor habit.
Here are the rules I follow when responding to stakeholders. I’ve highlighted the points of conviction in bold.
Rule I: If I don’t know the answer to a question, then that’s the answer
Scenario
Person A: Hey Zak, do we know if publishing changes via our CMS is allowed after 17:00?
Do
Me: Hey A, I’m not familiar with the release process of our CMS. Can you post this question into the main channel? B will be better suited to answer this.
Don’t
Me: Hey A, yeah I’m not sure to be honest. From memory this is ok but I could be completely wrong.
It’s better to be honest and say you don’t know than to say you don’t know with a feigned attempt at knowing. The latter wastes everyone’s time.
Rule II: If I know the answer to a question, then I answer it without caveats
Scenario
Person A: Hey Zak, after you’ve deployed your code will that also fix the similar bug we saw last week on the Log in screen?
Do
Me: Hey A, that’s right. This deployment will fix both defects.
Don’t
Me: Hey A, yeah I think that’s right. The fix should address both defects.
Trust yourself. If you know the answer, say it with conviction. A lack of conviction instils uncertainty in the person asking the question. They may be forced to ask someone else, wasting more time.
Rule III: If I’m being asked to predict an outcome, I emphasise that it’s a prediction
Person A: Hey Zak, we want to migrate this component to a common library. We’ve noticed that your team is one of its consumers. Do you know if migrating will cause any issues?
Do
Me: If we’re talking about a cut and paste migration then we’ll just need to update our references once it’s done. There is some complexity in how we use that component that may rear its head when we get to that point, but that’s not a reason to not perform the migration.
Don’t
Me: If it’s a migration it should be fine, I think. We might have some issues regarding how we use that component but I doubt it will be too hard to address.
This example is more subtle than the previous ones, but you can see how the second response lacks certainty, even with a prediction.
When we look at these examples, there are common phrases I use when I’m writing with conviction:
We will need to…
That’s not a…
It will fix…
I am not familiar…
In contrast, those responses lacking conviction use phrases such as:
I doubt it will…
…I think
I think that’s right…
…should address
I could be completely wrong….
Whilst these examples are contrived for this article, they are based on genuine interactions I’ve had with engineers throughout my career. It’s a stark contrast when you find yourself communicating with someone who has conviction in their writing. I always want to work with people like that, given the choice.
Stretch goal
Try employing this conviction when speaking. This is much harder as we don’t get an edit button when conversing.
In the software industry, every day is a training day. The learning never stops, and the repetitions never end. But we must be sure we’re practising the right methods during these reps. Contrary to popular opinion, practice does not make perfect; practice makes permanent. Instil your engineering routines with ethics like the ones above, and over time, you’ll see results.
If you made it this far into the article, thank you so much for reading.
Onwards 🚀
Zak