#12 Why Engineers Should Write
Writing is often an overlooked skill among software engineers because they’re usually focused on sharpening their technical chops. While that makes sense at the beginning of their careers, there comes a point where developing soft skills (alongside technical skills) becomes essential if they want to make a substantial impact and earn a seat at the leadership table. Soft skills include personal traits like communication, presentation, writing, and more, all of which help leverage your technical skills.
For now, let’s focus on writing.
Consider the diagram below. You’ve most likely come across documents that felt like Doc X—unstructured, confusing, hard to navigate, and trying to solve too many problems at the same time. Then there’s Doc Y—well-organised, clear, specific, and easy to comment and discuss.
How many times have you read Doc X? How about Doc Y?
Which brings me to this point:
If you’re a technical genius but struggle to communicate your ideas or solutions in writing, i.e. producing Doc Xs instead of Doc Ys, you’re missing out.
In this post, I’ll discuss why writing is crucial for engineers, explain what a Technical Design Document (TDD) is, and share a Notion template to help you get started!
Introduction
I’ll start by addressing a common, valid question:
“Shehab, I don’t care about writing. I should be focusing my time on getting better at programming and deepening my technical knowledge.
Aren’t these the things that drive my technical output and career growth? Why should I care about writing?”
Here’s my take on this:
You’re absolutely right about the technical stuff. Of course you should continue developing your tech skills. It is a valuable asset your company is paying you for.
But is that the only asset they’re paying you for?
No, they value that you: A) have the knowledge + skills to do the necessary work, and B) know how to leverage your knowledge + skills through communication.
Soft and technical skills go hand in hand. Communication is a core soft skill, and writing is a powerful tool for clear, effective communication.
Now, communication is a whole subject on its own, which we can go into another time. For now, let’s focus on writing. Let’s consider three engineering roles: junior, mid-level, and senior — and highlight the importance of writing in each role.
I. Junior Engineer:
One of your core responsibilities is developing software, and as a result, you’ll need to create Pull Requests (PRs). A PR is, in itself, a document—a code document—and the readers are your colleagues (i.e., developers). Are your code documents easy to interpret? Do you provide a description that explains the purpose of the PR? In other words, are your proposed changes clear to the other developers?
The description doesn’t have to be long or complicated; it can be bullet points, to-dos, etc. But you do need to write it—it makes reviewing your code easier and faster for others.
II. Mid-level Engineer:
In addition to a Junior Engineer’s work, you are also thinking beyond programming. You’re designing software solutions, whether they’re small or medium-sized features. You’re writing design proposals, sharing them with your team to get buy-in, and also reviewing other engineers’ work. This can be a short document with some pseudocode, diagrams, etc. It’s not necessarily a fully-fledged technical design doc, but you’re starting to build the habit of reviewing and writing high-level documentation.
III. Senior Engineer:
While your core responsibilities may vary depending on the company, as a senior engineer, you are typically a technical leader. You’re both an author and a valuable reviewer of the team’s technical documents. You communicate project ideas to a broader audience through writing—often involving engineering managers and other cross-functional roles. You might also need to set clear, written guidelines for your team, covering areas like coding conventions, PR review standards, backlog tasks, post-mortems, etc.
Each of these roles could be explored in its own post, but you get the idea.
Here’s a summary diagram
Practice makes perfect better
We all know that if we want to get better at something, we need to practice it. This applies to anything—writing your first line of code, reviewing your first PR, designing your first API, or creating your first feature.
The same goes for writing. We don’t practice putting our ideas into documents as much as we practice development (i.e., writing code). That’s why we often expect our writing to fall short.
Sure, writing can be painful at the beginning, but it can also be transformative for your career. At first, it will feel slow, confusing, and exhausting. But with practice, it gets incrementally better, just like programming. Personally, it’s always a cringefest when I look at my old university code, but I know I had to write “code that sucks” to get to the point where I can write “code that doesn’t suck as much.”
A few years ago, a mentor of mine shared this advice:
“If you want to get good at something, do it so many times until it becomes as natural as breathing.”
The key takeaway here is consistency. Don’t focus too much on how bad your first document will be. Focus on how you can make it slightly better every time.
I hope I’ve convinced you about writing by now. Next, let’s talk about what a Technical Design Document is. If you’re an early-career engineer, it’s a good resource to familiarise yourself with. If you’re an experienced engineer, it’s a document you’ll likely be writing and reviewing regularly.
What is a Technical Design Document?
A Technical Design Document (TDD) is a detailed plan that outlines the technical approach and steps for solving a specific problem. It acts as a comprehensive guide for developing features, software, or entire systems. It also serves as a shared reference for developers, designers, QA engineers, and product managers, ensuring everyone is aligned on the project’s technical goals and how to achieve them.
Writing a TDD forces you to think through edge cases, risks, and potential solutions. This process helps clarify the most feasible approach, so when it’s time to implement, the execution is faster and more efficient, having already done the mental work upfront. Also, putting ideas on paper helps you flesh out all the technical details, which may lead to activities such as doing tech spikes, coding a quick prototype, writing down technical challenges or risks, get early feedback, etc.
These activities are not necessarily done by one individual; others may contribute, creating an opportunity for you to lead the collaboration.
How to Write a Good Technical Document
Before you start writing, you first need to have answers to the following questions:
What is the purpose of this document?
What specific problem or challenge are you solving?
Who is the intended audience?
What do they already know or need to be informed about?
What is the scope of the project?
What are the boundaries of what this document will cover?
Make sure you have clear answers to these questions before you start. You don’t want to write a bloated document filled with technical jargon for a non-technical audience, nor do you want a shallow document that lacks depth for a technical audience. A document written with a specific audience in mind makes all the difference!
A good structure of a technical document typically includes the following headings:
Context - What background info or context (if any) is relevant to this project?
Introduction - What problem are we trying to solve, and why is it important to solve it?
High-level Design - What is the proposed solution, and what are the key components involved?
Alternatives - What other solutions were considered, and why were they rejected?
Milestones - What is the project timeline?
Risks - What potential challenges could affect the success of this project?
Open Questions - What aspects of the project still require clarification or input?
Appendix - Are there any supporting documents or links that could be helpful?
As a general rule, your tech documents should be created in a shared workspace (e.g., Google Docs, Notion, etc.) so that others can leave comments and provide feedback. This makes it easy for your colleagues to access and review your documents, much like with PRs. Also, try to keep the document concise; if there’s additional context that readers need, consider splitting it into a separate document and linking to it. This approach makes it easier for others to understand and comment on your proposal.
Finally, here’s a Notion template of a TDD document that I used frequently during my time at Faculty AI.
Conclusion
In conclusion, writing is more than just typing text in a document; it’s about developing the ability to communicate complex ideas clearly and efficiently. Software engineers who actively work on their writing skills indirectly improve the speed and quality of their work by sharing clearer insights and solutions that are easier to understand. For example,
Junior engineers who write detailed pull requests get their work reviewed and merged faster.
Mid-level engineers who write clear technical documents receive faster feedback.
Senior engineers who write clear project plans resolve blockers and concerns more quickly, leading to faster sign-offs for development.
As I’ve mentioned before, you should continue to develop your technical skills to improve your craft. But also focus on developing your writing today, and watch how it propels your career forward. 🚀