leadingIn(tech)#19: Writing matters
Hi there! 👋🏽
Welcome to a new issue of leadingIn.tech newsletter. I’m Roberto, and this is where I share ideas, practices, and learnings toward becoming a better leader in technology.
We are living in uncertain times, the news lately is filled by major tech companies doing layoffs and reducing their workforces. And now Twitter, just like a storm after the acquisition by Elon Musk, lots of people found their jobs to be terminated in just a matter of days. A measure that might seem precipitated and improvised. Especially when shortly after we hear that some of them were even fired by mistake (Whoops!) and then they realize they needed some of the people that were fired. Chances are that they will refuse to come back and that should not be a surprise.
There is a high risk of sacrificing writing things down for the sake of speed, either in favor of building things or making decisions. In this fast-paced world where we give that much importance to speed, sometimes we fail to see the value of documenting our actions. Probably because writing is hard, while it forces us to think, it takes time.
Shortly after the layoffs at Twitter happened, people started wondering how it would impact the stability of the platform. Why? Because we assume as normal that some people are “indispensable” to keep things running smoothly. Because there is valuable knowledge “in their heads“ that will be lost once they are gone. This feels to me like an organizational failure of assessing the bus factor risks.
Will we start seeing the typical “over capacity” messages? Will it happen that a server will come down, and someone will find a disk full of logs that used to be cleaned up regularly by a person who was just laid off? Maybe this is not the case at Twitter, but anyone that has been in software engineering long enough can relate to it.
We all love to build things, and once they are built we often forget that we will not be running them forever. How prepared is the system to be maintained by someone else after you leave voluntarily or involuntarily? How much documentation will the next person find at their disposal?
There are chances that there will never be enough documentation, or that it will become outdated too quickly, and some people might use it as an excuse for not writing at all. But I dare to say that documenting our work is as important as building the things we build. We usually say that software is in continuous evolution, so our written resources should be.
Writing allow us to materialize our thoughts and ideas, to be shared with the people around us. It also enables us to collaborate and evolve these ideas. Writing allows us to leave evidence of the context and the reasonings on why and how we built things.
Good documentation is a tool to support our second-order thinking, so we can understand the possible consequences of our decisions and the consequences of those consequences. See Chesterton’s Fence: A Lesson in Second Order Thinking. Understanding the context of why a fence was placed in the first place will help us understand the purpose of the existing artifacts, and having historical knowledge that helps us visualize the state of mind of the people to build it can help us understand the compromises they needed to take. Because of all of this, writing matters.
Writing matters, to you. To give you space to grow, and to effectively lead by giving autonomy to your teams. To improve your thinking and enrich it with others. To free yourself to be materially present for things to happen or pass on your knowledge.
Writing matters, to your teams. So they have room to work together as a team and better balance the workload, avoiding knowledge silos. To make better decisions with richer context and keep track of them for the ones that follow. To have time to log off and recharge when needed, to improve their engagement and ownership.
Writing matters, to your organization. So it grows in a healthy way and with resiliency. With enough flexibility to adapt to changes and to scale when it needs to. It matters so the culture is preserved and the context is shared with every person that joins it and not lost with those who leave.
Writing matters, to your customers. So they will enjoy the higher quality and stability of the product. So they know how your product works and how it will help them achieve their goals.
We can build better teams and organizations by not making ourselves indispensable because we didn’t write down everything we should have.
We can build better products by allowing the people who build them to make better decisions based on the greater context provided by our writings.
Your ideas matter, write them down.
leadingIn(tech)#4: Building teams that will outlive you
leadingIn(tech)#5: Managing your upstream communication
leadingIn(tech)#7: Working Backwards to identify the right talent for your team
leadingIn(tech)#15: Eliminate toil and give way to the team