Writing documentation is a great tool to improve software quality

I had a great day at work yesterday. I'm on the final stretch of developing a larger feature and as part of it, I had written code to make it feature gate-able. To figure out how to do that, I looked at other similar parts, tried to put 1 and 2 together and bit by bit managed to make it work.

At that point, I felt the urge to document this workflow since I was certain this wasn't the last time we'd add a gated feature and I wanted the experience to be more straight-forward for the next person: whether that would be a team mate or future me.

I have earlier written about how blogging is my favorite refactoring tool and documentation is in the same realm. It forces me to look at the code from a different perspective.

Learning how the system works

I would encourage every junior developer to work on documenting what they learn at work – whether it's on a more general level on your own blog or even better, very detailed in your work project. It forces you to dig deeper and understand the underlying system, helping you ask great questions from more senior developers and gaining better understanding of the code base.

I started my documenting project yesterday by taking a look at one of the permission models: I looked at all the different options and values you can give to the configuration, looked into how they were used in the project and built understanding for what the options are and how they work.

I then added documentation about the components and functions that one can use to limit what can be used based on the gates. At the end, I think I have a good documentation that someone can follow and get things done and have easier time even customizing it to their liking when options are explained.

I even added a few test skeletons at the end that developer can use to see how to write tests for these feature gates because I had a bit of trouble figuring it out initially.

Being the one who writes the documentation also exposes you to discussions with other people in your team who have originally built the features as you figure out why certain decisions have been made.

Surfacing bugs and improving quality

During my project, I discovered 5 bugs without writing a single line of code – simply by gaining understanding of the code and reading it with the mindset of "I need to explain this to someone else". 3 of them were existing bugs that hadn't been reported and 2 were potential bugs.

One being a case where to trigger the bug, it would require a regression to happen elsewhere in the code but since we were dealing with permissions, it could have led to some features leaking as a result to users.

The other one was a case where there was nothing technically wrong but when I was reading and writing, I realized that the wording of the interface gave me a stricter understanding of permissions than was implemented -> if someone else in the future had the same understanding, they might have introduced a bug.

It's interesting that the only reason I noticed these was because I was in the writing mode. It's such a powerful tool.

Surfacing inconsistencies

Another thing that you start to notice when writing is code style inconsistencies like naming.

For example, let's say that we'd have route guards and most of them are called requireAlphaPermission(field) or requireBetaPermission(field) and then one of them is called checkGammaPermission(field). They all do the functionally same thing for their own category.

Now, there's nothing wrong with either of these verbs. Both of them in isolation can mean the same thing and was probably the case that they were developed in different cases over time and not thought about that much. It's hard to notice the big picture around when focusing on feature development but they are so much easier to notice when writing and bringing them up as examples.

Consistent naming in case like this helps the code base because it makes it easier for the developers to have more intuitive understanding of what the functions do.

This kind of thing is also a great moment to have a discussion with your team or at least someone who maybe originally wrote the code or knows that part of the code best. My approach is always "Is there something I should know about the reason behind this? I'm thinking X but maybe there's history and decisions that I'm not aware of so let's work it out so I can document it properly (and change if it is indeed a bug or an oversight)".

It's never finished

Documentation is always a living organism: I expect team mates to make notes, add things and help make it better over time as our collective understanding improves.

My goal with documentation has multiple goals:

1. It helps me learn the system
2. It helps the next person implementing it
3. It helps people learn and make better solutions
4. To document the silent knowledge in a growing team