.png)
6 hours ago
2
You might not have noticed, but a large portion of a programmer's day involves writing: code, comments, emails, messages — whether in Portuguese, English, Python, or JavaScript — we are constantly converting thoughts into characters. Or, as I prefer to see it, transforming abstractions into concrete actions.
You could argue that comparing writing code to writing text (i.e., natural language) is pushing it. I disagree. In fact, I repeatedly insist that the most readable code is as close as possible to how a human would read it: variable and function names, and even the logical hierarchy of a computer program, should resemble what we're accustomed to in non-technical texts.
In 2019, I published an article called How to Become a Bad Developer, which became my most-read text since then. In it, I list behaviors that negatively impact the quality of a programmer's work. The last — and most important — mistake listed perfectly illustrates my point: write for machines, not humans. Here’s the conclusion:
Think about what makes a text enjoyable to you. It is usually concise, clear, direct, meaningful, and consistent. You won't enjoy reading when you can't understand the author, the narrative doesn't make sense, it's poorly written or weirdly formatted. Likewise, code that doesn't make sense and that you struggle to grasp is an excellent way to discourage readers. And just as an author who discourages readers is a bad author, a developer who discourages readers is a bad developer.But the need to write well goes beyond maintaining code that's readable, cohesive, and accessible to other humans. I'd like to explore other ways in which the habit of writing can not only boost your career but also make you a better person.
Writing as technical validation
The first article I published online was on June 18, 2015, exactly 10 years ago (I swear it was a coincidence). It was a post about converting data from JSON format to CSV using a framework called Meteor. No one cares about this topic today — either because Meteor lost its appeal, any AI can solve this problem in 2 seconds, or the mentioned libraries no longer exist. The fact is that this text hardly fulfills its original purpose of informing the reader.
However, it serves another equally important role: validation, a historical record that I've been in the game for at least 10 years. Two months later, I published my first article about React. Thus, it's undeniable and easily verifiable that I have at least 10 years of experience with React, the most widely used library for building modern interfaces.
And why is it important to show online that you know what you say you know? Well, this detail can make a difference when getting hired, for example. As mentioned in my article 3 Practical Tips for Growing Your Career as a Programmer" (available in Portuguese) my first job in the United States came from being cold-called by a company that found one of my articles online.
I've never been famous, and my texts never gained much traction (except for "How to Become a Bad Developer," which miraculously reached HackerNews front page), and this is not a case of natural selection in action (where someone successful teaches how to succeed in a niche where few can succeed). My texts had mediocre reach, were read by very few people, yet they still created an authority that qualified me for an international career.
You might think you have nothing interesting to say, but that's not true. As programmers, we solve puzzles every day. It's one of the few professions where we’re constantly learning something new. Crystallize this learning — it will benefit you, your career, and your readers (even if they are few).
Writing as a form of communication
Programming work is a collective effort — even if you're the only one writing code. If you have clients, you need to understand their difficulties and communicate solutions. If you have stakeholders, you must understand their demands and pain points, and argue the best way to address them. If you have teammates, you need to communicate your doubts, train new programmers, write documentation.
This necessity is further amplified if you work remotely. Without the tête-à-tête of a conventional office, you'll need to communicate more efficiently, often in writing (after all, remote collaboration is mostly asynchronous).
There’s a whole etiquette for remote work that’s essential for those who wish to excel in this mode: writing direct and concise messages, being clear in communication, not wasting others' time, etc. But the main aspect is what's known as rubber duck debugging.
Get yourself a duck, but if lacking, any action figure will work.Rubber duck debugging is an extremely effective method for debugging code (i.e., understanding why it doesn't work properly), which literally involves explaining the problem to a rubber duck.
This method works because when we explain something to someone, we consciously organize our thoughts, often clearing our minds. It's as if a light turns on during the explanation, and the solution becomes obvious — but only after we order our thoughts to explain it.
That's why whenever someone asks me for a quick call, I ask them first to write down their question. This requirement serves to: 1) allow work to flow asynchronously, and 2) serve as a rubber duck, where the mere act of writing (and consequently organizing thoughts to ask a question) reveals the solution. I've lost count of how many times this method worked for me.
Therefore, writing will help you better understand your field. Don't worry about readers; you're writing for yourself. If someone else benefits, even better. But the main goal is to solidify that knowledge internally. It's no coincidence that most reading retention techniques involve summarizing in your own words what you understood from a given chapter (a technique famously shared in books like How to Take Smart Notes).
Writing as a form of thinking
When I talked about writing as technical validation, we were at the most basic level of reasons to write: the utilitarian one, a kind of "advertisement" of your technical capabilities.
Then, we moved up to writing as communication. Here, this skill turns you into a valuable asset for those around you and a true team player. If the first level gets you a job, this one keeps you there.
Finally, at the highest level, writing develops your thinking ability. This skill transcends your job or mere programming and expands your understanding of the world, enabling you to see the reasons behind things, the best ways to organize a team, a company, and ultimately your own life. This is the stage that advances your career.
This is the real reason we should write: transforming the blob of data chaotically populating our minds into insights about the world, allowing us to work smarter.
If I haven't convinced you with this pseudo-philosophical argument, consider that in the age of AI, any model will ultimately code better than you. This is a competition we're doomed to lose. However, an AI will never think better than us — because it can't truly think. You don't have to believe me, though. A research team at Apple just released a paper named The Illusion of Thinking making the same claim (not really a breakthrough once this can be easily proved metaphysically, but let's not dive into that right now).
In this machine age, the winner will be whoever exercises their humanity — what only we can do. Thinking, creating, observing the world around us, identifying mechanisms behind things, concatenating ideas to solve problems — these are essentially human skills, as they emerge from human observation.
Writing trains your thinking. It's at this moment, alone with your thoughts, that you realize: do I really know what I think I know? Do I know what I want? Why do I want it? Practice not being an NPC, practice your understanding of the world, be humble enough to seek help from other texts, build your own knowledge network, and soon you’ll become indispensable not only at work but to everyone around you.
Write for yourself. Having an audience isn't essential for writing to be worthwhile. In some cases, readers might even hinder — write for others and you'll lose authenticity. Don’t fool yourself into thinking that just because programming is technical or boring, you’re excused from using words well.
Earlier this year, when I was setting up my Substack, I struggled to find the right bio. Everything seemed wrong and without character. Finally, I settled on a sentence that ultimately captures the essence of today's article: I write for humans and machines.
