There are multiple parts to being a software engineer. Writing is one of them. Writing code, of course, but that would be too obvious. I meant writing in a human-readable format.
I would like to prove my point by showing a myriad of reasons why it makes sense to treat writing as any other skill worth improving in a career in software engineering.
- Scaling knowledge as the team grows
- Giving better code feedback
- Explaining blockers
- Learning from mistakes (postmortems)
- Design documents
- Solving problems once
- Communicating remotely
- More influence
- Certain things just need to be persistent
- Writing forces you to understand the subject better
- Public writing
- References
Scaling knowledge as the team grows
As part of our jobs, we solve scalability issues of the systems we create. But as the teams grow there’s one more thing that needs to scale – knowledge sharing.
If you write you can scale your knowledge to other team members. Think of it as a database cache. When someone has a question, they don’t have to ask you every time, they can read a piece of documentation that explains the same thing. (Wang, 2020)
Giving better code feedback
If you work in a company that follows good practices of software engineering, chances are there is a code review process in place. It’s important to give clear feedback to quickly solve the blocking issues without getting into a never-ending exchange of comments in the code review tool.
But also from the other angle, writing a straight-to-the-point pull/merge request summary, listing edge cases and other changes can save a reviewer some time.
Explaining blockers
Things don’t always go as initially planned. And our work sometimes depends/is depended on by other teams. If we are stuck for either internal or external reasons it can help other teams if we explain the cause. They may reshuffle their priorities or possibly come and help. There’s a balance to maintain between explaining the issue thoroughly but also not getting too much into detail.
Learning from mistakes (postmortems)
And if things have already gone wrong, we can prevent the same scenarios in the future by learning from our mistakes. One way to do this regarding system outages is by running a postmortem analysis and producing a postmortem document (Beyer, et al, 2016). Other teams can read it and understand the past of the system and why certain solutions are in place.
Design documents
Before we start working, it makes sense, to sum up decisions on paper. Changing decisions at this stage is way easier and cheaper than implementing something in an incorrect way. For that, it makes sense to write a design document where we consider different possibilities. It makes sense to describe those rejected ones as well so that other teams could also learn from that and not consider the same options again.
Another benefit is that we have a common understanding before we start working on different parts independently.
Solving problems once
As we try out different options or solve certain issues, it makes sense to make the results of our research persistent. This way, when we come across the same problem again we don’t have to remember how to do things exactly. We can refer to our results from the past.
During my daily work, I run a personal debug log where I write things I did in case I needed to revert. I had multiple opportunities to refer to it to find certain commands and scripts.
Communicating remotely
In the software industry, it is not uncommon to work remotely or in a distributed team. There are even companies that don’t have their own office. In such scenarios, there’s usually a messaging tool that supports most of the internal communication (Slack, Microsoft teams, etc). Therefore it is yet another opportunity where we can practice clear communication.
I wrote an article where I share some tips on how to improve communication in remote teams that use Slack.
More influence
When there’s a group of people and decisions to be made, then for sure we’re going to influence others. If you write, you automatically have a chance to reach more people at the same time.
Certain things just need to be persistent
Proposals and decisions, coding guidelines, best practices, learnings, debugging guides, postmortems, code reviews, playbooks, API reference, and other types of documentation. These are the resources that just need to be persistent. If we practice writing we can make them better, improving the overall quality of work in our organization.
Writing forces you to understand the subject better
If you try to write something, especially when making a summary, you may discover that it is not that easy. The process of writing also involves a process of thinking and understanding so we can structure our knowledge better.
Public writing
Despite writing as a part of our job, we can also practice this skill under our own name. It could be a blog or a post. If we start producing content on the internet, we have more control over what happens when someone types in our name into the google search bar (unless we completely screw up the SEO).
Most of people are content consumers, so if we turn into content creators that makes us stand out from the crowd a little.
References
- Wang, S., The Coding Career Handbook. Guides, Principles, Strategies, and Tactics – from Code Newbie to Senior Dev (2020) – my notes from this book
- Beyer, B., Jones, C., Petoff, J., Murphy, N., Site Reliability Engineering: How Google Runs Production Systems (O’Reilly Media; 1st edition, 2016) – chapter 15 – https://sre.google/sre-book/postmortem-culture/
- Orosz, G., Undervalued Software Engineering Skills: Writing Well – https://blog.pragmaticengineer.com/on-writing-well/
- Orosz, G., Internal Politics Part 1 – https://newsletter.pragmaticengineer.com/p/internal-politics-part-1
