It’s very common for software engineers to enjoy writing code but dislike writing text. Who hasn’t felt frustrated writing documentation that quickly became outdated? Who hasn’t written a technical document that took longer than implementing the feature itself? It’s easy to lose sight of the true purpose of a good document, but it’s often that very document that allows us to scale our impact.

This text is aimed at professionals in Staff Engineer positions or above. That said, the ideas presented here apply to any engineer looking to expand their impact within an organization. Our company’s career ladder for Engineering sets a clear expectation of communicating effectively with different types of audiences. That alone is strong evidence of how valuable writing can be for professional growth.

Let’s explore a few reasons why you should consider writing more.

Nothing is more costly than building software or a feature that doesn’t solve the problem.

Understanding the problem well is essential to ensure the proposed solution actually meets the requirements. Often, the act of writing reveals that we’re missing information, metrics, or even clarity about the problem itself.

Using AI tools during the brainstorming process is encouraged precisely because they’re good at pointing out gaps and weak assumptions, but it’s still up to the engineer to properly articulate what is being solved.

A problem-description document creates space for other people and AI agents to contribute perspectives you hadn’t considered. A document allows the concept of the problem to be known, questioned, enriched, and refined collaboratively.

Who hasn’t found themselves in countless meetings explaining the same initiative or topic to different groups of people? We’ve all been there. Having to repeat the same pitch over and over to promote an idea is deeply inefficient. The number of people reached by your communication depends entirely on your presence and everyone else’s availability.

How do you communicate an idea without depending on meetings? How do you reach a large number of people without dedicating a huge share of your time?

The answer is simple: write a document.

A document that describes the problem, lays out the context, shows the relevant data and, when possible, proposes paths to a solution, has enormous power. It can be shared with multiple people at once. It can be read whenever each person has availability. It can be commented on asynchronously, calmly, without the time pressure of a meeting.

In the AI era, that reach goes even further: the document becomes a source for AI assistants. Writing it once serves both those who read the document directly and those who query an AI tool.

A question that comes up often is: “should I only write once I have a clear solution proposal?” The answer is no.

Documents that describe only the problem, with no proposed solution at all, can be extremely valuable. Presenting a well-articulated problem to leadership in order to get it prioritized is real, important work. It shows that you understand the business, that you can spot risks before they become crises, and that you can translate technical complexity into language that makes sense to decision-makers.

Unfortunately, reaching decision-makers isn’t always enough. Don’t expect every documented initiative to be prioritized right away. A good document can be picked back up months later, once the company’s context shifts or that initiative finally makes it onto the radar. The deep thinking about the problem will already be done by the time that moment arrives.

Technical discussions can produce excellent solutions, but all of it can easily be forgotten within a few months. Documenting decisions means creating institutional memory. It ensures the reasoning behind a choice doesn’t disappear along with the person who made it.

When someone leaves the team or the company, all undocumented context goes with them. Architectural decisions, design choices that made sense at a given point in time, known pitfalls of a legacy system, rarely used features that are essential for certain customers, obscure configurations, and known issues are all examples of knowledge that can vanish quickly.

Don’t fall into the trap of believing that being the sole holder of knowledge on a subject is an asset to your career. It’s exactly the opposite. Once you become the essential expert on a topic, you may never get the chance to broaden your horizons and take on new responsibilities, simply because no one else can do that part of your job.

Document concepts, resources, processes, and anything that can help your teammates act independently. Nobody wants to get a call at 3 a.m. to explain how to rollback a system. A well-documented procedure can be retrieved by a colleague or an AI assistant in an emergency; anything that was never written down stays invisible to both. That’s why it matters to keep documentation up to date and thorough.

A large part of a staff+ engineer’s work is invisible. Research comparing technologies, performance metric analyses, trade-off comparisons between different solutions, creativity in solving a brand-new problem, verbal discussions that set an important technical direction, and much more.

In verbal discussions, automatic transcription tools are extremely useful for formalizing what was discussed and decided. The transcript is raw material. It’s still up to the engineer to distill it into a short record of what was decided and why. The resulting document not only provides context for whoever wasn’t in the meeting, but also gives visibility to the Staff Engineer’s work.

For anyone pursuing career growth, this point is especially relevant. It’s common for engineers to struggle to clearly demonstrate the impact of their work. That happens, in part, because so much of it was never documented. The documents you’ve written are concrete evidence of the sophistication of your technical thinking.

Generative AI tools are already part of the daily routine of VTEX’s Software Engineering organization. Whether for writing code, reviewing PRs, exploring solutions, supporting incident investigations, or understanding unfamiliar systems. The fundamental factor that determines the quality of what these tools deliver is the context you provide.

An AI tool has no access to your team’s decision history. It doesn’t know why the current architecture was chosen over alternatives that seemed equally valid. It doesn’t know the business constraints that ruled out a certain approach years ago.

Technical documents like RFCs, ADRs, incident reports, and glossaries help AI tools produce better results, letting them factor in VTEX’s actual context rather than generic market knowledge. The richer the input, the higher the odds of good solutions. If the input is poor, the output tends to be poor too.

Investing in documentation becomes far more appealing when there’s a promise of a performance gain. The incentive has never been greater. So don’t wait to contribute. Start building context to increase your team’s potential.

If writing has never been a habit for you, getting started can feel hard. A few practical suggestions:

Write a short document describing the problem, its impact, what happens if it isn’t solved, one or more proposed solutions, and how to measure the initiative’s success.

Ask a teammate to review it before sharing it more broadly. That way you get feedback and can build confidence in the text.

A simple document that gets shared and discussed is worth far more than a perfect one that never leaves the draft stage. Starting with something simple reduces friction and makes us write more. The more we write, the better we become at this skill.

It has never been easier to produce text with the help of AI. With how far models have come, it’s very easy to expand a brief prompt into a detailed piece of writing. The trick is not to skip straight from a brief prompt to the final text: let the AI question you first, cover the gaps it exposes, and only then write. For those who find writing hard, this lowers the barrier: you don’t start from a blank page, you start from a conversation.

The trap here is forgetting who the actual target audience is. The whole point of documenting is to scale the distribution of knowledge. When generating documents with AI, review the output to make sure the information is easy to absorb: no bloated text, as much visual support as possible (images, diagrams, etc.), and a well-organized narrative.

For those in Staff Engineer positions or above, writing is one of the main vectors of influence beyond your immediate team. It’s hard to lead cross-team initiatives, contribute to strategic decisions, or develop other people without it.

Writing is also what takes you out of the equation. While a topic lives only in your head, you are its only channel: every decision that depends on it has to pass through you, and your impact is capped by your own availability. Once it’s written down, the knowledge stands on its own. It keeps circulating in rooms you’re not in and in conversations that happen without your presence. You stop being a blocker and become an enabler: for a less experienced engineer, a good document is often the shortest path to understanding a problem, following the reasoning behind a decision, and moving forward without waiting for you.

Feel free to reach out to the authors of this text and share your own experience with writing throughout your career. If writing isn’t part of your routine yet, try exercising that skill to expand your potential as a software engineer.

We would like to thank Isaque Lima, Rafael Bacelar, Kevin Chevallier and Tiaraju Smaneoto for their valuable contributions to this article’s review.

Further reading:

Staff Engineer: How to find time to work on broader-scope problems - on the VTEX Tech Blog, about the transition from Senior to Staff Engineer.