Why Improve Your Writing?

I’ve worked as a developer for 20 years, and I’ve always cared about clear writing. When I join a new dev team, the first thing I do is ask to update their onboarding docs. I capture what I learn in writing and encourage my teammates to do the same.

Sometimes, other developers ask me why I put so much emphasis on writing. Programming is a technical pursuit, so why should we spend time on a “soft skill” like writing? Isn’t that why we have technical writers and product managers?

Writing advances your career🔗

When you think of exceptionally talented programmers, you probably think of people like this:

• Dennis Ritchie, the creator of the C programming language and co-creator of Unix
• Grace Hopper, the creator of the first compiler
• Joel Spolsky, the co-founder of StackOverflow and Trello
• Jeff Dean, the co-creator of Google’s MapReduce and Bigtable technologies

Have you ever read any of their code? Probably not.

The reason you recognize any of these names is that, in addition to being good programmers, these people are also exceptional writers. They achieved impressive technical feats, but people noticed because they wrote books, papers, or blog posts that showcased their work.

You don’t have to be the next Dennis Ritchie for writing to help your career. At regular companies, the developers who rise to senior positions are the ones who communicate well–they write persuasive emails and clear design documents that get the attention of upper management.

I show writing techniques that improve efficiency within an organization in “Write Emails with Less Noise and Better Results” and “Write Useful Commit Messages.”

Writing scales infinitely🔗

One of the best things about software is how beautifully it scales. In what other field could you build something and deploy it to millions of users all in the span of a few minutes?

Writing enjoys similar scaling benefits. If a teammate asks you a question, and you spend five minutes answering them, you’ll spend those same five minutes when the next person asks you. And the next person. And then when that first person asks you again because they forgot what you said. If you instead write your answer in a team playbook, you can deliver the answer to a million teammates with no additional effort.

I’ve run multiple small businesses, and I always invested heavily in documentation. When I hired new employees, I never needed to handhold them through every task because we already had documentation.

When I sold my first business, thorough documentation was a major selling point in the sale. The seller didn’t worry that I’d walk out the door with all the company’s institutional knowledge. I showed them playbooks we updated regularly for all of our operations. After the deal closed, the new owner never had to chase me down for follow-up questions because I made sure our documentation captured everything they needed.

I explain how to write effective process guides in “Rules for Writing Software Tutorials.”

Writing deepens your understanding🔗

There’s an expression, “writing is thinking.” It sounds counter-intuitive. You think first, then write to capture those thoughts. In reality, writing and thinking are both part of the same iterative process.

Every time I write about a topic, it improves my knowledge or skill in that domain. Writing is extremely effective at exposing gaps in both knowledge and reasoning.

You’ve probably tried to explain something to a teammate, only to realize halfway through that you don’t understand the concept as well as you thought. Writing finds those gaps for you without the public embarrassment of not knowing what you’re talking about.

Writing also exposes gaps in reasoning. I often write playbooks or tutorials to explain my workflows. Every time I do it, I recognize opportunities to simplify or improve, even when it’s a process I’ve used for years. Writing forces you to justify your decisions. When you find yourself explaining why a step of your tutorial requires a sequence of eight commands, you can’t help but realize you should add a single convenience script instead.

I write public retrospectives about my business each month. And nearly every month, I sit down expecting to explain a business decision or strategy, but the process of writing about it reveals a better idea I’d completely overlooked.

I talk about how to build your knowledge and reasoning through writing in “Write Blog Posts that Developers Read” and “Write Effective Design Documents.”

Writing finds you clients🔗

On an Internet filled with infinite noise, how can you stand out? I meet developers who created an exciting new app but don’t know how to find users. Or they want to freelance but don’t know where to find clients.

I’ve always found users and clients by writing about my work. I launched TinyPilot, my most successful company, by writing about how I created my first prototype device. The post went viral, and I sold my first batch of inventory in a few hours. You’re probably reading this book because you discovered one of my blog posts.

If you’re looking for a job, good writing can land you a position. If you’re a small business owner, writing blog posts can bring you customers. If you’re a consultant, writing can bring you inbound clients.

The best part about writing is that it’s free. You don’t have to buy ads or hire a specialist. If you write something valuable for your target customer, they’ll find you organically.

I talk more about writing to find clients and users in “Find Customers through Blogging” and “Write Compelling Software Release Announcements.”

AI can’t write for you🔗

In the past few years, AI has exploded in both capability and popularity. People are using AI to do everything from writing their code to scheduling their haircuts. The bad news is that AI can’t write for you.

Okay, AI obviously can write for you. I constantly receive emails from people using AI to write to me, so I won’t pretend it’s impossible.

What I mean is that AI can’t offer you the benefits I’ve described here. In a world where anyone can use AI to generate a document, an AI-generated document won’t help you stand out. You won’t understand a concept better or spot flaws in your thinking when you’ve outsourced your reasoning to AI.

There are ways to leverage AI to improve your writing, and I’ll talk about those in “Using AI tools.”

How this book will help you🔗

Hopefully, I’ve convinced you it’s valuable to write well, even if you’re a developer.

The good news is that the bar for being “a developer who writes well” is embarrassingly low. Most developers don’t try, so you can be a top 10%’er simply by trying.

In this book, I’ll teach you practical steps to improve your writing. Some lessons are “quick win” techniques that improve your writing immediately. Others are more fundamental and require long-term practice.

If you want to improve your writing but don’t know what concrete steps to take, this book will show you a path.