Writing documentation is not a waste of time
Let’s play a riddle.
What is it? When you write it, no one uses it, but when you don’t write it, everyone desires it.
When you think about it, it can be anything, however the correct answer to my poor riddle is a project documentation.
Project documentation may be a notorious term in some esoteric circles. At some point in our lives, we’ve been there. We wrote shitload of documentation that no one reads. Sometimes, we wrote nothing, but then, the unlucky new guy needed onboarding and we were in need of some proper documentation. Most of us have been that new guy facing the deep dungeons of undocumented legacy code and we felt the torment. We picked up the torch, and with timid steps, entered the void, with no knowledge of what lied ahead.
The code is the best documentation
I think what it meant here is to avoid cluttering code with unnecessary comments. It’s not about documentation on how to run, thoughts, decisions, etc. It is more like related to code. If you are using type-hinting (or proper types), then with sane naming, there is no need to repeat the name of a method with its parameters inside the method docs. It’s better to describe the intent and what you want to achieve than what are you doing, since the code already tells how it works. Another thing is to be aware of outdated comments, they can be misleading. Forget to update comment and you make a pitfall for yourself of someone else. The code never lies, but comments may.
Sometimes, you run into some exotic and mind-bending piece of code that cries for explanation, especially if the guy that wrote it is no longer there. Here, you might use notes to help any hero wandering down there. However, I might argue it would be better to refactor that piece of nasty code, if possible, or encapsulate it into something meaningful. Consider using team decision records for making an exotic in the first case.
What about project documentation? During the active development, young developers are all about coding, but rarely anyone considers writing actual several English sentences of thoughts, how to run, how to build, decisions, gotchas, pitfalls, etc. It’s all obvious they say. We know how to run it… Even when someone writes something down, no one looks at it. This may be discouraging. You may also hear, let’s continue coding it, we can write docs later. The latter almost never comes. You only have a decent amount of now in your life. Over time, devs break discipline and documentation goes outdated, lost, or gets scattered all over the places. It is a good practice to have a team member who will be responsible not writing whole documentation, but to remind and organize everyone to write a few sentences about their work.
Any fool can write the code, but the true master maintains the documentation — Unsung hero
Having a proper tech documentation can be quite handy. Recently, we returned to the project after several months' break to find out that we are happy to have at least something to remind ourselves of. Guess which parts were the trouble for us? Yeah, you got it, the parts with no documentation. Even if we wrote that code ourselves and everything seemed to make sense back then. Imagine we had to onboard new developers as well, who did not know in what they got into. All of us had lost hours debugging and exploring how to run the same code we had run several months ago. So, what solves partial documentation or no documentation? Well, there is no point in sitting and cry about that. We gradually filled in missing pieces along the way, while we were rediscovering things. It put a strain on maintaining guides, decisions, thoughts of our work at the beginning, but we’ve built a habit out of it and it became a standard part of every task. Everything paid off eventually, the onboarding that lasted for a few months, now lasts for a few weeks, thanks to maintained documentation.
One of the hidden perks of having documentation is that keeps mental health in check. How? Imagine you are the guy who is on the project from the beginning and you are the only one that knows every corner. Because of that, a new team member will ask you everything. Well, you may say that’s ok, the living word is the best source of knowledge. But what about this scenario? A new dev arrives, and after that a new one… You’ll end up answering the same questions over and over, and I’m sure you have your own tasks to do instead of repeating yourself like a broken record. Say hello to unnecessary anxiety and stress. This makes you a single point of failure. You’ll want to go on vacation at some point, or you’ll be so pissed off that you would leave.
Endnote
As professionals, we care about our code and written communication. An essential skill that we must learn (or we already have) is transparency. When you write something down, being a decision or a how-to guide, it gives you clarity over your thoughts. You get a better look at the problem, you can see the flaws and you can learn something from that. It leaves the space inside your brain to be filled with other, more important matters. But you are not the only one who benefits from writing. All your teammates do, because then everyone will be on the same page.
