00:00:10.460
All right.
00:00:31.800
Without the benefit of body language or tone, you must take what lives in your head and compress it into words on the screen. It is also a powerful skill.
00:00:44.760
When you first start on the job, all you need to do is convince the person next to you that your code doesn't have bugs. They are probably already pretty good at determining that by looking only at your code. As time goes on, you might be asked to plan a short project and pitch it to your team. If they don't get it, your plan won't be chosen. As years go by, you'll start seeing problems that no one else does and will need to explain them clearly to people around you who may not be as technical. Eventually, those plans and designs will become more complex as your audience becomes wider. You'll be speaking with not only other developers, but also designers, product managers, customers, and executives. Without the ability to write clearly, you'll lose them.
00:01:10.500
At a certain point, your ability to communicate well will become even more important than your technical ability. So, do you write well? I'm Jordan Raine, and today we're going to look at how you can use the writing you already do to become a better writer.
00:02:03.119
This is the first page of "The Great Gatsby," a novel by F. Scott Fitzgerald. At just over 200 words, it's around the same length as the commit messages, pull request write-ups, and code review comments you'll write over the next few days. After three years of work, you'll write the equivalent of the entire "Great Gatsby" novel, about 50,000 words. Over a career, you'll write more than the entire "Lord of the Rings" series, including "The Hobbit," while on the job. So, if we're all writing a lot, why aren't we all excellent writers?
00:02:32.040
According to the 10,000-hour rule, which explains how practice can lead to mastery, we should all be competent writers after a few years on the job and good writers after 10 or so years. In 2018, a full 10 years after "Outliers" was published, its author, Malcolm Gladwell, explained this disconnect—why some people become better while others stay the same—by pointing to the quality of their practice.
00:02:49.500
There's clearly a difference between one person's ten thousand hours and another person's ten thousand hours. The people who practice in a focused way, receive ample feedback, and are working deliberately on improving their areas of weakness tend to see far more improvement over their ten thousand hours than those who do not, those who practice in a sloppy way. It's easy to let our writing practice become sloppy and instead focus on something more concrete, like learning a new programming language or framework. But writing is an evergreen skill; no matter where you work or what you do, your ability to write well will be appreciated by those around you and help your voice cut through the noise. With the explosion of remote work, your ability to communicate effectively with the written word has never been more important.
00:04:28.020
However, often by the time we're ready to open a pull request, we just want to move on to something else. What often fits into one of three categories starts with the nothing write-up. If you've ever reviewed a pull request like this, chances are you went straight to the code tab to figure out what it did. Sometimes that works fine, but at other times, the code may not tell the whole story, and you might miss something. In fact, this is probably the best way to sneak something past your reviewer. Or maybe you've seen a write-up like this that isn't short but also doesn't tell you anything new. It might describe the code changes but leaves out why they were made in the first place, or it includes information that's irrelevant to you.
00:05:40.560
This is actually worse than no write-up because as a reviewer, you don't know if the write-up is useful until you read it. If it's not useful, you still need to figure out why the code change was made, so you go over to the code tab. Even worse, you may learn to ignore write-ups in the future, leading to a vicious cycle where no one reads write-ups because they aren't useful, and so no one spends time on write-ups because no one reads them.
00:06:09.479
Finally, the last PR write-up is noisy. It creates a wall of text and code with useful information that is hard to understand, mixed in with information that isn't relevant. This really makes you work for it.
00:06:56.140
So, what does it take to make these write-ups look more like this good write-up? Well, first we need to understand what we're doing and why. Writing at work is often strangely inhuman. The topics are complex, and the tone is often impersonal. We write things we would never want to read ourselves, and that leads us to the first thing to keep in mind when writing at work: most readers would prefer not to have to read your document at all. Larry McHenry, the director of the University of Chicago's writing program, sums up the purpose of academic writing like this: 'Why are they reading? Because they think it's valuable to them.' Therefore, your writing needs to be clear, organized, persuasive, and more than anything else, valuable.
00:08:05.520
If it's not that, nothing else matters. This principle applies to what we do as well. It's not like a novel or a movie—after a new movie comes out, you don't rush off to Wikipedia to read the plot summary because you don't really care about the plot; you care about the experience, the popcorn, and hanging out with friends. However, when you write at work, it's different. Your readers aren't interested in an experience; they're interested in the value you can provide, and the easier you make it for them, the better.
00:08:41.760
If they get lost while reading, they'll grow impatient and skim, or they'll stop reading altogether. But this is at odds with their tendency to change how we sound at work. We become more technical and less friendly; we replace simple words with fancy ones and exchange action for passivity. This leads to sentences like, 'Participants were tested under conditions of good to excellent acoustic isolation.' While I understand the words, I can't process the meaning until I rewrite it in my head as, 'We tested the students in a quiet room.' Unlike the first message, the second message is efficient; as quickly as we read the words, we understand what they mean.
00:09:41.620
This kind of writing puts the reader first and makes it easy for them to understand what is being said. In the workplace, where the reader reads to be informed, this kind of writing is ideal. But contrary to its effortless form, clear writing isn't easy to create, and the first problem is an unexpected one: you know too much.
00:10:23.760
When you sit down to write a piece, there's a good chance you know more about it than the reader. After puzzling over a bug for a few hours, all the details about what happened and how to fix it are fresh in your mind. Like a professor teaching a first-year computer science class to high school kids, this creates an imbalance. In the early 90s, a psychologist at Stanford named Elizabeth Newton ran an experiment to explore this kind of asymmetry between two people. She divided 80 students into two groups: tappers and listeners.
00:10:51.600
Tappers were given a list of well-known songs, like 'Happy Birthday' and 'Jingle Bells', and asked to pick a song and tap it with their finger on the table for one of the listeners. Before they began to tap, they were asked to estimate how likely it was that the listener would correctly identify the song. On average, the tappers thought 50% of the listeners would guess the tune, but after 120 trials, only three songs were correctly identified—that's only 2.5 percent. Even though it was pessimistic, the tappers thought at least 10 percent of the listeners would guess correctly. So why were the tappers so optimistic? If you're the one tapping on the table, the song is playing in your head.
00:11:52.780
When you tap the rhythm to 'Happy Birthday' on the table, it's hard to imagine someone not recognizing the pattern; it just seems so obvious. But as the listener would tell you, it's not so easy being on the other side. This is the curse of knowledge, and it may explain why good people write bad prose. If you've ever asked for directions in a strange city, you've probably experienced what it's like to be the listener—you're hearing the words, but they're just not sticking. Meanwhile, the person explaining it is vividly imagining themselves turning each corner. This shows up at work almost every day when it comes to explaining what you've done; what comes out misses many of the steps you needed to take to understand the problem initially.
00:12:43.540
Reversing this effect is challenging, even when you're aware of it. A good rule of thumb is to assume your readers know less about the subject than you think they do. Even when the reader is familiar with the subject, they'll often find a brief refresher of terms and jargon helpful, as it brings their existing knowledge to the forefront.
00:13:18.340
Another cause is relying too much on abstractions. As we learn something, our brain exchanges concrete examples for concepts. These are easier for us to recall and act as shorthand when speaking with someone who is also familiar with the concept. Rather than saying, 'You've duplicated the same code in three different places, and it's probably a good time to extract it into a separate method,' you just say, 'Can you dry this up?' This saves time—so long as you're speaking with someone who can easily recall what 'dry' means. If they can't, you've lost them. Working in a field so packed with abstraction, concrete examples can be a much-needed break for your readers. Instead of writing, 'This will prevent an attack vector, where we add so many items that it causes issues in the UI,' swap the abstract terms for concrete equivalents like, 'This stops people from making the page slow by limiting the number of items that can be added.' In other words, concrete is better than abstract.
00:16:31.680
In other words, examples can make abstractions appear concrete. Perhaps the best way to avoid the curse of knowledge is to describe step by step how a process, a bug, or a system works. For example, when opening a PR with a bug fix, instead of just explaining what you did to fix the bug, guide the reader through the experience: how was the bug triggered, why does it occur, and what other fixes did you try? Then, after explaining all of that, explain what you did and why it worked. This is effective for two reasons: first, it forces you to prove to yourself that you understand how it works—gaps in your understanding become more obvious the more you write. In fact, our ability to reason about a topic increases when we write about that topic.
00:17:43.160
Second, walking through a process step by step helps bring the reader through the same sequence of events that made the concept clear to you. If you needed those steps, chances are your reader does too. If you follow this pattern, you'll find that your writing builds on itself sequentially in a perfectly crafted piece. Each sentence will provide information that informs the reader while raising new questions in their mind that are then answered by the next sentence. This creates momentum that tugs the reader along.
00:18:41.160
Here's an example from a recent pull request that added a new feature to GitHub: you can now create markdown code blocks quickly using a keyboard shortcut. Okay, cool! I learned something new! Now, how do I use it? To use it, highlight some text, then hit command e. Perfect! But what about multi-line blocks? If you highlight more than one line, you'll get a multi-line code block; otherwise, you'll get an inline code block. But ideas rarely flow from your mind to the keyboard in the way that is best understood by the reader. So, unless you're part of the fortunate few who can write perfectly on the first go, get ready to edit.
00:20:30.300
When writing software, we rarely get things right in one go; we offset our imperfections. We refactor early and often, each time making the code better for our future selves. Many of us relish this activity; it's a kind of spring cleaning for our code to go from messy to clean, from disorganized to tidy. If you rely on refactoring, it usually goes something like this: first, write something that runs. The variable names can be nonsense, the performance can be awful, and it can break all the rules in the book—so long as it gets the job done. Once there, we refactor and transform that mess into something we're proud of. In "Bird by Bird," Anne Lamott describes a similar process for writing fiction: 'The other thing I really believe in is writing really, really shitty first drafts.' A lot of writers write bad first drafts; they write frighteningly bad first drafts.
00:21:56.760
I don't think you can know what you're doing until you're probably a whole draft through it. Those shitty first drafts lead to good second drafts and terrific third drafts. William's answer takes it further in his classic book on non-fiction writing by showing two pages from the final manuscript, peppered with marks and revisions. Even after being rewritten five or six times, it could still be made tighter, stronger, and more precise. This repeated refinement is the key to writing well; a relentless pursuit of improvement that ultimately produces work worth keeping. If you know how to refactor, you already know this process: you take something that works but not well, find a shortcoming, and apply a transformation to make it better. Then you repeat, just like we would with code.
00:22:58.200
Let's look at three ways we can refactor our words. Good writing is compact; every word earns its place. The first draft is yours—be as wordy as you like. But then comes the ax! Or, as Stephen King's first editor, John Gould, put it: 'When you write a story, you're telling yourself the story. When you rewrite, your main job is to take out all the things that are not the story.' My wife and I recently moved into a new home, but before we did, the builder emailed us an update: 'At this point in time, we are currently waiting for an on-site inspection by local trades representatives to ensure recent changes to the electrical system will support the new appliance package.' The new appliance package can't be delivered until they sign off on the new work. Or, in other words, your fridge will arrive later than expected. Clutter can make the most important parts of your work disappear into a wall of text; just like your code, sometimes the best thing you can do is delete.
00:24:10.260
You can often cut up to 50% of the content without losing any information. This is one of my favorite parts of writing, because hitting delete is easy and can transform a jumble of words into something lean and confident. So, let's declutter a pull request: 'This PR fixes the author filter dropdown, which appears on the issues page. When I tried to reproduce it locally, it wasn't working at first, and then I tried it on production, and I didn't see it either. I almost closed the issue as
00:25:28.080
won't fix,