How to Write Good Documentation as an Software Engineer
June 11, 2025
Software engineers must excel at more than just coding. Ryan Peterman, a Staff Engineer at Meta, shared a LinkedIn post that caught many developers' attention. He argued that the most important language isn't Python, C++, Rust, or Java—it's English. His reasoning was simple: software development requires constant collaboration, and writing becomes essential for that collaboration.
Think about your typical work week. You write technical design documents, participate in technical discussions, and review code. Each of these activities requires clear written communication. While Peterman specifically mentioned English, the core principle applies to any language you work in—strong writing skills directly impact your career growth as a software engineer.
Why Write Documentation? What Are the Benefits?
Before diving into how to write good documentation, let's address a fundamental question: why write documentation at all? Many engineers view documentation as a burden and avoid it when possible. However, understanding the concrete benefits of good documentation can shift your perspective and improve your long-term career prospects.
From a personal standpoint
Writing helps you think more clearly. When you have a complex technical design floating in your head, the act of writing it down forces you to think through the details more thoroughly.
Your influence extends beyond your immediate presence. Documentation saves time by scaling your knowledge. Consider onboarding new team members. Without documentation, you might spend an hour explaining the same system architecture to each new hire. With good documentation, new team members can learn independently, and you can focus on higher-level strategic work. This O(1) cost approach to knowledge sharing becomes increasingly valuable as your team grows.
Documentation makes your contributions visible during promotions. Louie Bacaj, a Senior Engineering Director at Walmart, has written extensively about how good documentation can impact career advancement as much as good code. When your documentation helps dozens of team members understand a complex system, that impact becomes evident during performance reviews and promotion discussions.
From a team and company perspective
Critical knowledge stays accessible. Teams change. People leave, reorganizations happen, and domain knowledge often walks out the door with departing employees. Recovering lost tribal knowledge costs significant time and resources. Well-documented systems and processes prevent these knowledge gaps from becoming expensive problems.
Senior team members can focus on high-impact work. When someone asks a question for the first time, answering it might take five minutes. But if you can predict that others will ask the same question, that's the perfect time to write documentation. This approach lets senior engineers spend less time on repetitive explanations and more time on architecture decisions and mentoring.
New team members can work independently. New hires often worry about asking too many questions and disrupting their teammates. While healthy teams encourage questions, the ideal situation is comprehensive documentation that enables new team members to be productive quickly without constant guidance.
Good Code Doesn't Replace Documentation
After reading these benefits, you might wonder: if code is written well enough, do we really need documentation? After all, if the code is clear and self-explanatory, new team members should be able to understand it by reading the implementation directly.
In practice, well-written code doesn't eliminate the need for documentation. Code shows you how something works, but it rarely explains why it works that way. Technical documentation serves a different purpose—it explains the reasoning behind decisions.
Consider this scenario: You're reviewing a service that uses Redis instead of PostgreSQL for a specific data storage need. The code clearly shows the Redis implementation, but without documentation, you can't understand why Redis was chosen over PostgreSQL. Was it for performance reasons? Scalability requirements? Cost considerations? The technical design document should explain these trade-offs, helping future maintainers understand the context behind the decision.
When documentation captures the "why" behind technical choices, future maintainers won't immediately think "What was the previous developer thinking?" Instead, they'll understand the reasoning and make informed decisions about whether to maintain or modify the existing approach.
Questions to Consider Before Writing
Before you start writing, clarify several key questions. This preparation ensures your documentation provides genuine value to readers.
Identify Your Audience
The most important aspect of writing is knowing who will read your work. Technical documentation might target teammates in your group, engineers from other teams, or product managers without technical backgrounds. Each audience requires a different approach because they bring different levels of context and background knowledge.
For readers with limited technical background, provide sufficient context so they understand why your work matters. For example, if your technical design document states "optimize web page LCP to under 1 second," readers without performance knowledge might not grasp the significance.
Adding context—such as "industry standard is 2.5 seconds, and 1.5 seconds represents excellent performance"—helps readers understand that achieving 1 second is challenging and valuable.
When your audience includes people with varying technical backgrounds, use hyperlinks for additional context. This approach lets knowledgeable readers skip basic explanations while giving others access to background information they need.
Define the Most Important Message
After identifying your audience, determine what information matters most to them. Consider what readers hope to learn from your documentation. Most people read documentation because they're facing a problem and need a solution.
Think about the problem you're solving. What question are you answering? Focusing on this core issue ensures your documentation provides value and respects readers' time.
If you have multiple important points to convey, try this focusing exercise: "If I had only one minute to explain this to a reader, what would I say?" Or ask yourself, "What three things must readers absolutely understand?" These questions help you prioritize the most critical information.
Different Documents Have Different Focus Areas
Even when writing for the same audience, different types of documents require different approaches. Understanding these distinctions helps you set appropriate expectations and deliver the right content.
Consider these three common document types:
Technical introductions focus on what a new technology does. These documents help readers quickly understand a new tool or system's purpose and capabilities.
Technical deep dives focus on why something works the way it does. These documents explore underlying principles and provide thorough explanations of complex topics.
Project retrospectives focus on how something was accomplished. These documents help future teams learn from your experience and avoid similar mistakes.
Before writing, clarify which type of document you're creating and emphasize the appropriate focus area. This alignment ensures readers get the information they're looking for.
Support ExplainThis
If you found this content valuable, please consider supporting our work with a one-time donation of whatever amount feels right to you through this Buy Me a Coffee page.
Creating in-depth technical content takes significant time. Your support helps us continue producing high-quality educational content accessible to everyone.