The best code in the world means nothing if you can't explain what it does
I have spent years editing technical writing for founders, engineers, and product teams who build genuinely brilliant things and then struggle to describe them in a way anyone outside their own head can follow. This is not a rare problem. It is the default state of most technical teams, and it costs them more than they realize: slower onboarding, confused stakeholders, documentation nobody trusts, and code reviews that turn into arguments because nobody wrote down the reasoning in the first place.
Writing is not a soft skill bolted onto engineering as an afterthought. It is a core part of the job, and the developers who treat it that way tend to outpace the ones who don't, even when their raw technical ability is identical.
The gap between knowing and explaining
Every editor who has worked with technical clients has a version of this story: a developer sends over documentation for a feature they built themselves, and the writing is nearly incomprehensible. Not because the developer is careless. Because building something and explaining something are two entirely different cognitive tasks, and most engineering education spends all its time on the first one and almost none on the second.
When you write code, the compiler or the interpreter forces precision on you. Skip a semicolon, misname a variable, forget to close a bracket, and the thing simply does not run. You get immediate, unforgiving feedback. Writing has no compiler. You can produce a paragraph that looks complete, that took real effort, and that says almost nothing useful to the person reading it. Nothing stops you from shipping unclear writing the way something stops you from shipping code that won't build.
This is exactly why the skill has to be learned deliberately. It will not develop as a side effect of getting better at engineering. I have watched senior engineers with a decade of experience write commit messages and pull request descriptions that are genuinely worse than what a junior engineer produces, simply because nobody ever told them writing was something to practice.
What writing actually does for a developer
Writing forces you to think in a straight line. When you're deep in a codebase, your understanding of a system can be tangled, associative, full of context that lives only in your head: the three failed approaches you tried before landing on this one, the edge case you remembered from a bug two years ago, the tradeoff you made without fully articulating it even to yourself. Code doesn't require you to untangle any of that. It just requires the final logic to work.
Writing does require you to untangle it. A clear paragraph forces you to decide what actually matters, in what order, and why. Engineers who write regularly, whether that's documentation, design docs, or even just detailed commit messages, tend to think more clearly about their own systems, because the act of writing keeps exposing the parts of their reasoning that were fuzzy.
I have edited enough design documents to know the moment when a writer realizes, mid-sentence, that the architecture they were about to defend doesn't actually hold together. That realization almost never happens while coding. It happens while writing, because writing is where hidden assumptions get dragged into daylight.
The documentation nobody reads and why that's a writing problem
Bad documentation isn't usually bad because the writer didn't know the subject. It's bad because the writer wrote for themselves instead of for the reader. This is the single most common failure I see in technical writing: a document that makes perfect sense to the person who already understands the system, and almost no sense to anyone else.
Good technical writing requires imagining a reader who does not share your context. It requires deciding what to explain and what to assume, and getting that judgment right is genuinely hard. Too much explanation and experienced readers feel patronized and skim past the parts that actually matter. Too little and newer readers are lost by paragraph two. Developers who write well have usually built an internal sense for this balance, and it shows up not just in their docs but in their code reviews, their Slack messages, and the way they onboard new teammates.
I've built a career around helping people say clearly what they actually mean, and the pattern I keep running into with technical clients is a kind of quiet frustration. They know their subject better than almost anyone. They've solved hard problems. And then they sit down to write about it and the words come out stiff, defensive, over-explained in the wrong places and rushed in the right ones. It's not a confidence problem. It's that writing is a distinct craft, and craft takes deliberate repetition, the same way debugging or system design does.
What strikes me every time is how fast this improves once someone actually treats it as a skill instead of an afterthought. Not months of practice. A few genuine attempts at rewriting something with a specific reader in mind, and the improvement is visible. The barrier isn't ability. It's that almost nobody tells developers this is worth their deliberate attention, so it stays in the category of things they'll "get better at eventually," which in practice means never.
Where this shows up beyond documentation
The developers who write well have an advantage that extends past their commit history. Pull requests get approved faster when the description actually explains the reasoning instead of just listing the diff. Bug reports get resolved faster when they're written with enough precision that someone else can reproduce the issue without three follow-up questions. Promotion cases, especially at companies that value written communication, often come down to whether an engineer can articulate their impact in a document, not just point at a dashboard.
There's also a less obvious benefit: writing well makes you a better reader of other people's code and documentation. Once you've had to make hard choices about what to include and what to cut, you start noticing those same choices, good and bad, in what other people write. You get faster at spotting the design doc that's hiding a real problem behind vague language, or the code comment that's technically accurate but explains the wrong thing.
How to actually get better at it
This isn't about becoming a novelist. It's about a handful of habits that compound.
Write the plain-language version first. Before writing a technical explanation, try writing one sentence that describes what the thing does as if to a smart colleague on a different team. If you can't do that, you don't yet understand the thing as well as you think you do.
Read your own writing out loud. Awkward sentences reveal themselves fast when spoken. So do sentences that are doing three jobs at once when they should be doing one.
Cut the sentence that explains how you feel about the problem and keep the sentence that explains the problem. Technical writing gets weighed down by hedging and justification. State what happened, why it matters, and what to do about it.
Ask someone outside the immediate context to read a draft. Their confusion tells you exactly where you skipped a step in your own head without noticing.
Treat commit messages and pull request descriptions as real writing, not throwaway text. They are read more often than almost anything else you produce, usually by people trying to solve a problem under time pressure, which makes clarity there worth more than it looks.
The actual case for learning this
Code communicates with machines. Writing communicates with people, and people are the ones who decide whether your code gets used, maintained, funded, or understood at all. A brilliant system explained badly gets misused, abandoned, or rebuilt from scratch by someone who never understood why it was built that way in the first place. A mediocre system explained clearly gets adopted, trusted, and improved by people who actually understand what they're working with.
Learning to write isn't a detour from engineering. It's the part of engineering that makes the rest of it matter to anyone but you.
Top comments (0)