There’s no doubt that the main skill of any software developer is to write good code regardless of the programming language and the platform he is specialized on. This means he must be able to write code that is concise, readable, testable, performant, etc. For this, a developer needs to master not only programming languages and frameworks but also a rich set of tools (like IDEs), design patterns and development practices, like Test-driven Development (TDD).
Besides this fundamental set of skills there’s an additional one which is oftentimes overlooked or undervalued by many developers: Writing. In my opinion, good writing skills are almost as important for a developer as his ability to write good code. Moreover, I’m convinced that this skill will get more and more important in the future and is a distinguishing factor between an average developer and an excellent one.
Allow me to justify the reasoning behind my opinion.
As professional software developers we are already used to write a lot of documentation, right? We are documenting our code, document architectural design decisions and development guidelines, write down instructions for building and deploying our software and prepare manuals for the users of our applications. If only this would be true.
In reality we as software developers try to get around writing down stuff as much as possible. We are also pretty creative when it comes to the reasons why we do not do it: it’s more important to ship features, the code itself and especially the accompanying test cases act as documentation, etc. For some developers, the ones with lots of experience and discipline, this might actually be true. In the past, I was actually very fortunate to witness this in some rare occasions.
Unfortunately, this does not hold true for the vast majority of professional software developers. Especially, it’s a real challenge for the junior colleagues because of their lack of experience. I think that it’s a good investment for every developer to acquire good writing skills while he is improving his core skills as a developer. There are at least three reasons for doing this.
Write for your future self
In some cases you might be working as a sole developer on a project. Maybe it’s even just an application for your personal use. So why should you bother and waste time to write down even the least amount of proper documentation? You already know everything about the codebase because you have build it by yourself.
Let me ask you a question: Have you ever looked at some code you’ve written a couple of days, weeks, month or even years ago? I bet it took you some time to understand how the code works, what it tries to achieve and what edge cases it handles. At least I’ve been in this situation more than once.
This is not surprising since you had a lot more knowledge about the problem you wanted to solve when you were working on it. However, after some time has passed this mental model as either become blurred or even completely lost. Additionally, in the meantime you probably learned lots of stuff about how to do things better or more elegantly.
That’s why I always tell people to write down the stuff about the code that is not immediately obvious. A good indication about when this is appropriate is when you worked on the solution for a longer period of time until you could finally make it work. Your future self probably will have problems to reproduce your thought process to understand what you did there.
The same applies also to writing down things about how to build and deploy the application and all the other instructions which are necessary to get it working again.
Write for your teammates
In general, professional software development is a team effort. The reasons for writing things down are basically the same as for solo developers. However, with a team you have a whole lot more reasons to acquire and practice good writing skills.
First of all, you need to write things down for the rest of the team to understand the reasoning behind decisions and reproduce the way more complex business logic works. Additionally, it’s important to write down all the guidelines for handling certain implementation details like error handling or asynchronous communication between software components. Additionally, the instructions for setting up a development environment, working with certain tools or using development practices are important.
Oftentimes the people making up a software development team have a very different background with a wide range of knowledge and experience. Therefore, it’s important to write down the non-obvious things and sometimes even the obvious ones. Doing it in a way that is easy to understand requires practice like any other skill you want to master.
The immediate benefit for this is that you might not need to waste your precious time to explain things again and again. It will also help you now and then to save time by easily finding things you did forget because you do not do it on a daily basis, for example setting up your development environment when you get a new laptop.
Last but not least good writing skills are very important in a changing work environment. It becomes more and more common for developers to work remotely in distributed teams. Those setups have some unique challenges when it comes to communication. Most of it is asynchronous through messages in Slack, comments on Pull Requests, user stories and bug reports in JIRA or documentation in Confluence. For an efficient communication it is essential to be able to write down what you want to say in a concise way that is easy for others to understand.
Write for the community
Nowadays we can leverage the combined knowledge of the community simply by googling for solutions to problems. This way we can make our lives easier by simply copying snippets of code other developers have already provided for free. Just doing this without really understanding what you just copied has it’s own risks but this is another story.
By writing things down and share it publicly, for example in forums like Stack Overflow, wikis, projects on GitHub or even your own blog makes you a good citizen by giving something back to this community you benefited from. In the end, this might open up opportunities you would not have dreamt of before. Who knows?
I ask teammates repeatedly to write down a simple blog post once they played around with a new framework, came up with an elegant solution to a problem or fixed some nasty error with some piece of software or library. Oftentimes the answer is that this would be wasted time because the discovery is not very valuable, others would find this boring, etc. In my opinion this is simply not the case. If you work on a problem for some time or learn about a new framework you probably know more than 80% of your teammates or other people in the community. Therefore taking the time to write your discoveries down and sharing it with the community will be helpful for others as well. And even if no one else might find it useful it might still be valuable for your future self.
How to get started
So, how can you get started to improve your writing skills. Like any other skill it requires some practice and determination. Don’t get scared or discouraged by this. Just try to be aware of it.
As a professional software developer there should be countless opportunities during your work day to practice your writing skills. Whenever you write some complex piece of code write down concise inline documentation. Whenever coming up with some best practices share them with your teammates in a wiki. Whenever you finish a feature write down instructions for your users to use it. Just take a couple of minutes per day and you’ll see how this will improve your writing skills dramatically in an amazingly short amount of time.
If you are more determined you can start your own blog and practice your writing skills by setting aside a couple of minutes per day to produce new content. For example, you can write about the things you learned during your work day or write down step-by-step instructions for how to accomplish certain things. As I said before, even if no one is reading your posts you can use it as a reference for your future self. But I would bet that your content will get a valuable source of information for other developers, too.
Summary
I’m convinced that by practicing your writing skills and becoming a good writer you will become better at communicating with your teammates, clients and other people. This way you will also increase your value as an employee by distinguishing you from your peers. You differentiate yourself since you will make better use of your time by communicating more efficiently and reduce rework by providing helpful documentation. If this is not a convincing reason I don’t know what else might be.
I’m curious what you think and what your experiences are in this regard. Get in touch via Twitter or LinkedIn and share your thoughts and stories.