What nobody tells you about working internationally: the problem isn't your English

When I joined Joyjet, a French software shop serving clients across multiple countries, my English was far from ideal. My French was nonexistent. And even so, code reviews weren't my problem. Delivery architecture wasn't my problem.

My problem was explaining why I had made a decision.

Not the decision itself. The reasoning behind it.

There's a very common belief among Brazilian engineers who want to work on international teams: the bottleneck is English. I believed that too for a while. I took courses, improved my pronunciation, expanded my technical vocabulary.

But when I actually started working with teams in France, in the United States, and later remotely with American companies, I realized that language was the easiest problem to solve.

The real problem was something else entirely.

What international teams expect that nobody teaches you

In well-structured international teams, the expectation isn't that you write better code. The expectation is that you can trace your own reasoning in public.

Making good decisions isn't enough. You need to be able to articulate the decision in a way that someone in a different timezone, with a different cultural and technical background, can understand the trade-off you made, without having to ask you anything.

That sounds obvious when you read it. But it's far rarer than it seems.

At Photozig, working with a team in San Francisco, the first time I opened a PR with a migration from AVFoundation to FFmpeg in a video editing flow, the description was technically correct. It explained the what. It didn't explain the why, didn't document what I had discarded, didn't mention the maintenance cost the approach introduced.

The feedback I got wasn't about the code. It was about the absence of context.

"Why FFmpeg over AVFoundation natively?" A simple question that revealed a problem I'd been carrying for years without realizing it.

I was making good decisions but not communicating them. And on a distributed team, a decision that isn't communicated doesn't exist.

The "Code That Explains Itself" Syndrome

Engineers who came up in a Brazilian environment often carry an implicit belief that good code explains itself. That if the architecture is solid, the reviewer will understand.

I thought that way too.

The problem is that it works when you're sitting next to the person you work with, when you both attended the same meetings, know the same business constraints, heard the same conversation with the product team last week.

On distributed teams, nobody absorbs that context through osmosis. Nobody was in the meeting. Nobody knows you ruled out option A because the infra team blocked the dependency. Nobody knows the current approach is temporary.

And the cost of that doesn't show up in the PR. It shows up three months later when someone refactors something "wrong" because they didn't know it was right for a specific reason.

The real challenge of an international career isn't language, it's documentation

What international teams train, consciously or not, is the ability to document reasoning.

RFC before implementing. ADR after deciding. PR descriptions that explain the context, not just the diff. Code comments that explain the why, not the what.

This isn't bureaucracy. It's the mechanism that allows a distributed team, with people across three timezones and natural turnover, to keep making coherent decisions over time.

When I migrated from VIPER to MVVM in a reputation module on a codebase with multiple teams working in parallel, that decision needed to be documented in a way that any new engineer could understand the motivation without asking me. Because I wouldn't be available. Because the team would change. Because in six months nobody would remember the meeting where we discussed it.

Documenting reasoning isn't a writing skill. It's an engineering skill.

What this has to do with seniority

Seniority in an international context isn't just technical depth. It's the ability to operate asynchronously without losing coherence.

A senior Brazilian engineer can have impeccable architecture and still come across as junior on an American team because they can't make themselves understood in writing, without synchrony, without the cultural benefit of the doubt that exists when you're all in the same office.

And the reverse exists too. Mediocre international engineers who come across as far more senior because they communicate well, document well, create context before they need it.

That tilts the playing field in a way nobody likes to admit.

What I changed

I started treating the PR description as part of the code. Not as a formality.

I started writing the reason behind each relevant decision before implementing, even if it was just a paragraph in an issue.

I started asking, when reviewing other people's code: "why not X?" Not to challenge. To build the habit of articulating why alternatives were discarded.

It sounds simple. It took longer than it should have for me to realize that was it.

The honest trade-off

There's a real cost to this. Documenting reasoning takes time. Writing a good decision record is harder than writing code. And on teams under heavy delivery pressure, this habit is the first thing to get sacrificed.

The problem is that the cost of not documenting doesn't show up now. It shows up when the team grows, when the engineer who made the decision leaves, when the codebase starts accumulating decisions with no memory attached to them.

And then you stop understanding the very system you built.

What an international career actually taught me

After working with teams in Brazil, France, and the United States, the most consistent difference I observed wasn't in the stack, wasn't in the processes, wasn't in the technical level.

It was in the proportion of engineers capable of communicating technical reasoning in writing, clearly, for someone who wasn't there when the decision was made.

And that skill isn't taught in an English course. It doesn't come from a certification. It doesn't show up on a resume.

It shows up the first time someone on the other side of the world reads your PR and understands, without having to ask you anything, why you did what you did.

Or they don't. And then you realize you have work to do.