How do you become a Better Software Engineer? Become a Better Writer
In the world of software engineering, technical skills are often emphasized as the primary path to improvement.However, there's a powerful tool that's often overlooked in a developer's toolkit: writing. Enhancing your writing skills can significantly boost your effectiveness as a software engineer.
Now I know what you’re thinking - engineering is already tough - now I need to learn how to write as well? But the advantages of writing are so beneficial that ignoring it would be a missed opportunity.
Why Write?
1. Writing Helps You to Clarify Your Thought Process and Think Clearly
When you write, you're forced to organize your thoughts in a logical, coherent manner. This process of structuring your ideas on paper (or screen) can reveal gaps in your understanding or flaws in your logic that might not be apparent when the concepts are just floating around in your head. By articulating your ideas in writing, you're essentially debugging your thought process, leading to clearer, more refined solutions to complex problems.
2. Writing Helps You to Pick Up Where You Left Off
Software development often involves juggling multiple tasks and projects. This constant context switching can often leave developers feeling frazzled and it’s easy to lose track of where you were in your thought process when you return to a project after some time away. Detailed notes and documentation act as a mental anchor, allowing you to quickly reorient yourself and resume work efficiently. This is particularly valuable when dealing with complex systems or long-term projects.
3. Writing Helps Communicate Your Ideas to the Rest of the Team
In collaborative environments, clear communication is key. Writing allows you to articulate your ideas, proposals, and solutions in a format that can be easily shared and understood by your teammates. Whether it's explaining a new feature, proposing an architectural change, or documenting a bug fix, well-written explanations ensure that your ideas are accurately conveyed to others, reducing misunderstandings and promoting smoother collaboration.
4. Writing Helps You Solicit Feedback from the Team
When you put your ideas in writing, you create a concrete artifact that others can review, comment on, and critique. This written format allows for asynchronous feedback, giving team members time to thoroughly consider your proposals and provide thoughtful responses. It also creates a record of the discussion, which can be valuable for future reference or for onboarding new team members.
Documents are also a great vehicle for catching any errors, mistaken assumptions or anything was missed in the planning. Time and time again it has saved my butt on many occasions.
5. Writing Helps Provide a Reference You Can Keep Coming Back To
Software development is often iterative, and decisions made early in a project can have long-lasting impacts. By documenting your thought processes, decisions, and the rationale behind them, you create a valuable resource that you and your team can refer back to throughout the project's lifecycle. This can be particularly helpful when revisiting old code, troubleshooting issues, or considering future enhancements.
Also, for smaller teams with constant turnover, this documentation can be life-saving. A big org can absorb the loss of a single senior engineer but for a tiny startup - this could literally put them out of business. Well-written documents helps ease any transition.
6. As You Level Up In Your Career, Planning Becomes More Important
It is often said that engineers write less code the more senior that they get. At the higher levels of the profession, the bulk of the job shifts to planning - designing systems for scale, assessing trade-offs, weighing which technologies to use and thinking of what could go wrong.
Writing is your greatest ally in this high-level decision-making. Choosing to forego it may mean putting a ceiling on your career.
7. Good writing is the key to unlocking better results from AI
As AI gets better every day, your ability to articulate your problems and clarify your requirements to the LLM makes the difference between amazing and mediocre results. AI is the great gamechanger. It’s changing the world as we know it. Prompt engineering is one of the techniques which help produce the most useful results from the models. And surprise, surprise - good writing matters more than ever. AI may be smart but it can’t give you the answer if it doesn’t understand what you’re asking for.
Practical Tips for Incorporating Writing into Your Software Engineering Practice
1. Create a Document for Every Ticket. Write Out a Detailed Plan
Before diving into coding, take the time to create a document for each ticket or task you're working on.
It doesn’t have to be complicated. This is not middle school - we’re not looking for a thousand word essay here. For most tickets, a simple checklist or bullet points of goals and to dos can be a gamechanger.
Use this document to outline your approach, consider potential challenges, and plan your implementation strategy. This practice not only helps you think through the problem more thoroughly but also provides a reference for you and your teammates as the work progresses.
2. Take Advantage of Commonly Used Documents in Software Engineering
The software engineering field has developed several standard document types that can help structure your thinking and communication. In a lot of bigger orgs with more standardized procedures, you might in fact already be required to do these things. Familiarize yourself with these and use them to your advantage:
a) Design Documents: Use these to outline the architecture and high-level design of your software. They help you think through system components, interactions, and potential trade-offs before you start coding.
b) Requirements Specification: This document helps clarify what the software needs to do, ensuring that you and your stakeholders are aligned on expectations. Writing detailed requirements forces you to consider edge cases and potential issues early in the development process.
c) API Documentation: Ever used a public API with documentation that looks like it was put together by a fortune cookie writer having a bad day? Terrible documentation can be infuriating and turns people away from using your product. Clear, comprehensive API documentation is crucial for both internal and external developers. Writing this documentation often reveals inconsistencies or areas for improvement in your API design.
d) Technical Specifications: These documents dive into the nitty-gritty details of how a feature or system will be implemented. Writing tech specs helps you think through the implementation details and potential challenges before you start coding.
e) Post-mortems or Incident Reports: After resolving a major issue or outage, writing a detailed report helps you and your team learn from the experience and prevent similar problems in the future. You could even go the extra mile and write a pre-mortem, outlining what could go wrong and planning contingencies.
f) Runbooks: These are step-by-step guides for carrying out specific operations or troubleshooting common issues. Writing runbooks forces you to think through processes systematically and can be invaluable for maintaining system reliability and reducing mean time to recovery (MTTR) during incidents.
g) Deployment Checklists: Creating and maintaining deployment checklists ensures that all necessary steps are followed during the deployment process. Writing these checklists helps you anticipate potential issues and standardize your deployment procedures, leading to more reliable and consistent releases.
By incorporating these writing practices into your software engineering workflow, you'll find that your thinking becomes clearer, your communication more effective, and your overall productivity enhanced. Remember, becoming a better writer is a skill that develops over time. Start small, perhaps by documenting your daily work or writing brief design proposals, and gradually expand your writing practice.
Don’t be intimidated. Nobody is expecting Shakespeare. Be clear and concise, using only the words you need. Avoid drowning your subject in technical babble or corporate buzz speak. Think Hemingway, not James Joyce.
So, embrace writing as a powerful tool in your developer toolkit— your next best career move might be learning how to write better English, not better Rust.