Of Tracked Changes and Diffs: Moving from Editorial to Engineering
I started my professional life as a writer and editor while in college. Some people were poets, and some were budding screenwriters, but I was an omnivore, which meant I ended up in all kinds of writing workshops. Personal essays both comedic and tragic, fiction ripped raggedly from the provocateur, and other tentative revelations of the soul, all offered up in stapled sheafs for me and my fellow undergrads to mark up and offer suggestions, some of them even helpful, in the goal of making a better piece and making us all into better writers. I thought I was learning to make a good sentence, to find the right mellifluous word for the right moment. But mostly, I was learning to critique and to be critiqued, and it’s that skill that followed me into my second career as a software engineer.
Code reviews and pull requests (PRs) don’t themselves point to the deepest essence of the author (or mine don’t, at least), but they come with their own vulnerabilities - and other similarities too.
Editorial workshops find ten to twenty writers (in my experiences, all students) gathered around tables. The writer hopes for a thoughtful review of the themes and structure, followed by more granular parts, sentences and scenes and transitions, concluding with any last questions from both sides. At its best, this is encouraging and affirming, highlighting strengths as well as areas that would shine better if worked over a bit more. Alas, sometimes it quickly devolves into a pack of 17-to-21-year-olds, new to this “tactful interpersonal relations” thing, working out their incomplete thoughts about literature and themselves in the form of scribbled notes and vague discontent. It can get messy.
Code reviews are a bit more straightforward, I’ve found, though they can still be just as fraught. This vulnerability can feel pretty sharp - the engineer and their code, perhaps showing their progress with a technology they’re not really sure of yet, their work put before several colleagues who the engineer would really like to impress. Ideally, this can be encouraging and affirming, highlighting strengths as well as areas that would shine better if worked over a bit more. Alas, sometimes it quickly devolves into a group of people, who may or may not be emotionally or chronologically fairly underdeveloped, working out their feelings about computers and themselves in the form of unhelpful verbal assaults, in which useful advice may be embedded. It can get messy.
I’ve weathered both, and I can advise you on a few common tactics to help you get through either with less pain, more insights, and better relationships. It’s all about getting feedback on the right things from the right people.
Use the critique to narrow down what you don’t know yet
In editorial workshops, you may think you have a handle on your plot until your writing sees the light of day and the attentions of people who aren’t party to your interior monologue. In code reviews, you may have thought you understood how something worked, maybe even got your new feature working via the judicious application of copying and pasting from Stack Overflow, but when another person asks you what line 41 actually does, it may all fall apart.
It doesn’t feel good, no. The act of writing, of either explaining or doing, illuminates what you do understand and narrows down what you don’t. And this lets you make a plan, which lets you improve.
There are ways to get past the feelings to get the most from the opportunity of a critique:
1. Understand what you can reasonably get from a critique
This takes time and practice in code reviews and editorial workshops alike. But once you know what you can get from others who are reviewing your writing or code, you’ll be able to ask better questions and have more reasonable expectations. How much time will you get with a given coworker when they’ve been assigned to assess your PR? Is the cultural expectation to get straight to the point in the most efficient way, or is it acceptable to explore the subject at hand more and perhaps research together? Once your PR is being evaluated and worked through, will the reviewer be willing to work together with you to remedy shortcomings or perhaps even pair? Once you have an idea of how code reviews work in your organization, you’ll know what you can reasonably expect and ask for.
2. Celebrate when you do fully understand something
It can’t be all punishment all the time. When you’ve gotten a handle on a scene or made a really good, reusable React component, you deserve that high-five. Now go teach someone else to do it.
3. Bias toward action rather than agony
Self-flagellation, in my experience and observation, has yet to help anyone better understand containers or sonnets or a new Python library. If someone points out something you don’t get yet, ask them for a resource they’d recommend for better understanding. Don’t let wounded feelings get in the way of learning. It’s a gift when someone helps you better understand where your comprehension is falling short.
Get feedback from the right people
Whether because of timing or staffing, sometimes the right people don’t assemble to get you the feedback you really need. In writing classes, it could be that you’re at the mercy of the registrar - or just that someone workshopped a really gutting piece of memoir just before your light comedic essay and they couldn’t switch gears in time. In code reviews, it could be that the person assigned to your PRs just isn’t suited to understand what you’re trying to do.
In both cases, if the situation doesn’t provide, the onus is on you to find the right people and learn from them.
Look for folks who:
Can critique without condescending
Ask questions before dictating
Listen
Get regular feedback from them.
If you’re coding or writing as part of your job, you likely won’t have the option of choosing your critics, but you can add to them. If you find you’re not getting what you need from your team, talk to your manager, seek out a mentor elsewhere, try to create a peer review group (at work or not).
And if your workplace is really that full of prescriptive blowhards, maybe start polishing your resume too.
Better work comes from collaborating and listening
In editorial workshops, the wrong comment at the wrong time can make it very hard to hear anyone over the rush of your feelings. It isn’t any easier to hear difficult truths about your code. But in either case, checking out means losing valuable information that you need to have in order to grow, and you do both yourself and your reviewer a disservice by shutting down.
In both situations: strive for mindfulness, assume good intentions on the part of the other person, and keep your mouth closed to give your ears a chance to do their job. Here are a few ways to make that more possible.
1. Set expectations
If you ask for what you need in code reviews, you’re more likely to get it. If you really want a closer look at a particular function or if you just respond better to written criticism than spoken, it’s yours to ask for. You may not always get what you request, but people are usually pretty glad to oblige. They’re taking the time to give you feedback; it’s in their interest to make it more digestible for you.
2. Create routine
If you do code reviews regularly, with a predictable format, hearing critiques within that format will sting less across time. Taking criticism well and usefully is a skill that requires gaining stamina across time to work well. Reducing the number of surprises within the situation will make it easier to get used to. It also gives you a chance to get those expectations into your team’s regular process.
3. Ask questions instead of lashing out
If you can feel a biting retort sitting sharply at the tip of your tongue, take a deep breath and ask a question instead. It will buy you time to calm down and will also make it more likely that you’ll get something useful out of the situation. It’s true of a lot of situations: sometimes discord begins to blossom darkly when two people have mismatched context. Offer everyone a chance to correct it before damage is done - and before you earn a reputation as someone who can’t deal with constructive criticism
Cultivate radical candor and humility
In both workshops and code reviews, much of this responsibility should go to the professor, facilitator, manager, or lead, though it’s up to individual contributors to really run with these qualities.
In workshops, it’s easier to be vulnerable and try audacious new things if you know that comments will be useful, or at least appropriately encouraging, rather than having to weigh the risk of someone being unkind about an early draft. The same is true in code reviews - psychological safety is what lets teams function and makes innovation possible. If people don’t have to worry about defending themselves while explaining their work, they’re much more likely to push the horizon of the possible (or at least introduce you to a cool new tool that could be really useful a few months from now).
Even if you aren’t the authority in the situation, you can still demonstrate the respect you want to receive. You can embrace humility as the reviewed and as the reviewer. Here’s how.
1. Work with kindred spirits to create a space where honesty is worth it
If the space to deliver hard truths kindly and to ask for difficult feedback safely doesn’t exist at your work, perhaps it’s your role to demonstrate it. Find one or two people who get the benefits of speaking plainly, honestly, and respectfully and begin to cultivate a space where you all begin practicing making this normal - in emails, in critiques, in meetings, and in all the routine and vital communication. Once that begins to feel ordinary, reach out to someone else, perhaps a manager, and begin evangelizing. It may seem daunting at first to folks who aren’t used to it, but I’ve found that people often find it to be a revelation when they see it demonstrated by people who are committed to being kind, conscious, and effective.
2. Dishonest equilibrium != safe or effective
Dishonest equilibrium, or the false appearance of a tranquil space full of good actors, can be just as stifling as a workplace full of open hostility. In the latter, people may keep their observations to themselves rather than face a fight; in the former, though, the illusion of peace may be enough to keep some people quiet for fear of being the buzzkill. The result of both is the same: missed insights and opportunities.
3. Remember that everyone is learning all the time
That goes for writing, coding, and critiquing. Even if people have been at it for decades, they’re still contending with old experiences, new ideas, and the weird tendencies that everyone has. No one is a finished product; everyone has something to teach and learn. We all have something to gain from respecting other people’s space to grow and get better.
Go forth and learn and teach
The clip-and-save, tl;dr version is this: know what you need, know how to listen, and know what you want. Put words to your desires. Use routine and specific expectations to ease into the often awkward situation of critiquing and being critiqued. Be generous and forgiving but also give the gift of your real read on things - and, when this is offered to you, receive it graciously. Be specific, actionable, and kind. We all have something to offer each other, and by being respectful and honest, we can make the most of these opportunities.
If you never have, consider taking a writing workshop sometime. I’ve found that comparing the two situations has let me better understand both very familiar and very new practices and concepts. And be sure to let me know what you think of these parallels - I’d love to hear from more fellow hybrids.