Busting the myth that developers can't write

Busting the myth that developers can’t write #

It’s an annoying stereotype that developers don’t know how to write, speak, and otherwise communicate. The stereotypes – such as the developer looking at their shoes while giving a technical talk or the developer who prefers to work in a shadowed basement – tell a story of people so specialized they can’t do anything but code.

The image is an unfair one, a myth we could bust by citing amazing talks, linking thoughtful articles, or pointing to any of a multitude of developers who maintain a thoughtful social media presence. If there is a nugget of truth, however, it’s revealed by the most common writing task assigned to developers: Documentation.

The current state of documentation does little to bust the myth of developers’ writing skills. Software architect Sagar Behere, for example, wrote a whole blog post taking apart Hugo’s documentation. After giving some constructive criticism, Behere ended by saying “It felt like the official Hugo docs were the last place I should look at if I wanted to learn how to do something with Hugo.”

Unfortunately, this isn’t uncommon, despite the fact that the effects of poor documentation can be costly.

Documentation is important for both end-users and developers themselves. End-users benefit from documentation that makes the product easy to use and understand, which improves the experience and lowers support requests. Developers benefit because the effort it takes to produce good documentation will make the development process faster and better as the team works toward explaining and articulating how the product works.

The trouble isn’t that writing documentation is hard. The trouble is that writing documentation calls for skills developers often haven’t learned or haven’t had cause to practice.

The good news is that you don’t need to start from the ground up. Writing documentation is its own specialized skill but it’s still writing, which means you can steal from other fields and adapt the advice to your needs. To get you started, we’ve collected three writing tips from the worlds of fiction writing, nonfiction writing, and business writing that will help you write better documentation.

1. Verlyn Klinkenborg: Think about what you want to say and what you’ve said, not what you “should” say #

Verlyn Klinkenborg is not the first person you’d think of when looking for advice about writing documentation because he’s most well known for writing books, stories, and essays about rural life and its meditative qualities.

But Klinkenborg also wrote one of the better books on writing out there, a book called Several Short Sentences About Writing, which contains a lot of advice developers writing documentation can learn from. One of his primary recommendations is for writers to focus on thinking about their intentions and examining how those intentions translate onto the page.

In the book, he writes that “It’s hard to pay attention to what your words are actually saying. As opposed to what you mean to say or what you think they’re saying.” This problem actually gets harder the longer you try to write something. The more time you spend writing and rewriting, the easier it is to lose track of what your words really mean and how effective they really are.

Writers like Klinenborg actually have an advantage here because they can reference a long history of legendary writers and compare the effectiveness of their writing to the people that came before them. But considering how bad documentation often is, the same method can be a trap for developers.

If you think too much about what you “should” do and about what your documentation “should” contain, you can end up regressing to the mean and regurgitating mediocre practices. Instead, it’s best to focus on what you’re trying to say instead of ticking off supposedly necessary steps in an inherited process.

This focus can lead you to greater depth and more precision.

Precision is easier to achieve when you’re concise. As Klinkenbog writes, “It’s easier to tell what you’re saying in a short sentence.” When you focus on what you’re trying to say, you can step back from what you’ve written, read it as if you were an outside observer, and determine whether it’s really clear.

A focus on intention can also lead to greater depth. If your task is to write a design specification, for example, it might be tempting to just do a checkbox exercise and close the ticket with minimum effort expended. But if you think about the intention behind writing the design specification, such as helping people write tests or create technical documentation, you might think beyond what’s merely “minimally viable.”

Instead, if you focus on what you truly want the documentation to accomplish, you can be creative and exceed the standards set by other companies and provide a service to the reader that surpasses their expectations.

2. Stephen King: Focus on the goal #

As a writer, Stephen King is primarily famous for two skills: Writing good horror books and writing a ton of good horror books (65 novels and counting). In his book about writing, called On Writing, King emphasizes focus and movement – the momentum that delivers the reader from beginning to end.

When a reader tries out your book (or essay or documentation), one of the biggest and most likely risks is that they just get bored. According to King, one of the most likely reasons a reader gets bored is because the writer, while they were writing, became “enchanted with [their] powers of description and lost sight of [their] priority, which is to keep the ball rolling.”

This might not seem to apply to documentation at first – how many developers describe anything in documentation, much less get so excited about the description that you could call it “enchanted”? Seen another way, though, it becomes relevant: When you’re writing documentation, it’s easy to lose track of the ball and either explain too much or explain too little.

Even if writing documentation isn’t your favorite task, over-explaining might still be an easier trap to fall into than you think. It’s often very easy to go too deep into the specific details and in doing so, bore the reader.

If you’re a Twilio developer, for example, it probably benefits you to be passionate, if not obsessed, about the intricacies of SMS messaging. But if you’re a Twilio developer writing documentation, you need to be able to step back from that passion and focus on the end goal of informing your readers at a level that benefits them.

That said, under-explaining is just as likely. Even at companies that prioritize documentation, which isn’t all of them, coding tends to come before writing. It’s tempting to explain the easy parts and the parts you know well while skipping over or generalizing the parts that are harder to explain.

Struggling to explain something, however – especially when you’re trying to do so concisely – doesn’t mean that you don’t understand it.

Think of recipe blogs, which are so often run by experienced cooks that nevertheless struggle to explain their process. A food blogger will sometimes slip anecdotes in between steps in the recipe – adding color but sacrificing cohesiveness. There might also be a lot of tacit knowledge they know but don’t think to communicate, such as the distinct sound of browning butter or how different ovens can have different hot zones that affect bake times.

Documentation requires a balance between over- and under-explaining, a balance where the documentation remains concise while still explaining all the essential details. Just like with programming, you might end up spending a lot of time thinking and designing and planning to arrive at just a few lines of text (or code). That’s a success.

Your goal is to explain the most relevant information as concisely and as to-the-point as you can. Give your reader a clear thread they can both follow from beginning to end.

3. Paul Graham: Avoid the curse of expertise #

Paul Graham, co-founder of Y-Combinator and father of entrepreneurial children, has also made a name for himself as a writer by writing essays on topics ranging from technology to business and from the death penalty to writing itself.

Perhaps owing to his experience as a developer or his experience hearing hundreds of startup pitches – many of which likely (especially if the founders took the time to read Graham) focused on extremely narrow niches – Graham is wary of the so-called “curse of expertise.”

In a 2022 essay titled “Putting Ideas into Words,” Graham refers to writing as an “exacting” process, as a way to “test” your ability to communicate to a reader you don’t know. Graham writes that “You have to pretend to be a neutral reader who knows nothing of what’s in your head, only what you wrote.” This is harder than it sounds.

Consider an influential psychology study that demonstrated the curse of expertise. In the study, the researchers asked participants to tap out a well-known song on a table, such as Happy Birthday, and guess how many listeners would correctly guess the song from the taps alone. Participants guessed that 50% of the listeners would guess the song; in reality, only 2.5% did.

This study revealed how much expertise can obscure our ability to communicate. The tappers could hear the song as they tapped but the listeners heard nothing but taps. The tappers heard the song so clearly, because the tune was in their heads as they tapped, that they overestimated the effectiveness of their communication by an order of magnitude.

To combat this problem, Graham sends his work to “the stranger” and when the stranger has feedback, he incorporates it and sends it back. “It takes me many cycles before I can get an essay past the stranger,” Graham writes.

Graham provides another useful metaphor in a 2005 essay called “Writing, Briefly.”

In this essay, Graham compares the task of writing essays to the task of writing pop songs: Writers have to “write for a reader who won’t read the essay as carefully as you do, just as pop songs are designed to sound ok on crappy car radios.”

Note that this doesn’t mean you should “write down” to your reader or otherwise assume ignorance or stupidity. Instead, you should meet them where they are and write with their context and needs in mind.

Yes, the readers might benefit from reading the documentation front to back, just in the way a listener might benefit from listening to FLAC files on high-fidelity headphones, but you have to write toward the average person, the person who will hit CMD-F as soon as the page loads and the person who will belt along to songs skittering from tinny car speakers.

Practice makes perfect (or at least better) #

A lot of writing advice is targeted at writers, people who have learned to enjoy writing to some degree. But for many people, writing at length is an all too often torturous process that resurrects memories of reading Shakespeare in high school English class and cramming half-formed ideas into five paragraph essays.

There’s a bit of advice all three of the writers we’ve cited agree on: Writing takes practice. Klinenborg writes that “There’s no magic here. Practice these things, and you’ll stop fearing what happens when it’s time to make sentences worth inscribing.” King writes that “You can learn only by doing.” Graham writes that “the way to get better at writing essays is to practice.”

Is it cheesy to close this article by advising you to practice? Yes, but it’s cheesy because it’s true and if you take this truism seriously, it’s also helpful: It’s okay to have a hard time writing as long as you keep writing and keep getting better.