Documentation is boring
It is true, documentation is boring, but this is mainly because we aren’t taught how a document should be, what its purpose is, and what are its benefits. From the beginning, we start with the idea that it is a thing that needs to be done, but unnecessarily and just messes with our coding time.
Do I know everything about my application?
When I started making my first solo application, I started directly implementing it (‘Don’t start writing code link’), without thinking too much about what I wanted to achieve, how I will do it, what third parties I needed to integrate, and even how the things should be connected. In the first two-three months, everything was ok: I implemented the user onboarding process (register, login, etc), the 3–4 features that were on my mind, and it seemed fine. The application was working pretty much ok, the performance was decent, so good so far. But then I started realizing that some features were unnecessary and didn’t bring value to the user, it was just an idea that I had in my mind and went for it.
Interesting, right?, it was my application, but when I looked closer it seemed that in the end, I didn’t know too much about it. Then I started putting my initial thoughts in a paper to be more visible and have more direction over what I wanted to do. After I had everything in front of me, the ideas that were by brainchild have birth to more questions than what I initially had: “Should I do this after I do that? Is there a library that can help me to do this quicker? It is really necessary to implement it? I don’t see how it could help the user.” Then I started answering all these questions and, in the end, to have at least a base documentation for my business requirements.
For the technical part, I was shocked when I started looking closely at my code and I found out that the duplicate code and unnecessarily complicated code thrived. By writing directly code, I didn’t stop to think about what was the best type of architecture that I could use for my implementation and also how the different logic could be used in multiple places. By realizing that, I started my journey in UML diagrams, which helped me very much. You don’t need to create every type of diagram, it is enough to choose the ones that feel best for you and make you quickly remember what you need to do, or what you already did. Also, I started using proof of concept for small things that I wanted to do but weren’t very clear, or where I wasn’t sure that could help me to achieve the final flow.
Do you remember everything?
Funny story, in my first year as a developer I didn’t write anything in my agenda or in a specific application. I thought that I will be able to retain all kinds of information: how to open a solution, what it is the business and technical flow, why it was implemented like this etc. But after the solution grew and the context switched quickly I started forgetting things and every time I needed to allocate time to remember what I did a month or five months before. After a while, it became very frustrating.
‘Sadder but wiser’, as the proverb says, I started using an agenda in the first phase where I wrote almost everything. And very quickly I found it very useful because the time I used to take to remember what I did decreased to ten-fifteen minutes and I could resolve my tasks more quickly. Then I migrated to different applications (Notion, Miro, OneNote) to be able to sync all my notes to all my devices, and there you can have multiple ways of arranging your information.
You will encounter the same problem when you will start developing your own application, After some time you will forget why you started something or how the flow is working. Here you can see a benefit of what we talk about above: documentation, proof of concept, and diagrams.
Does your new colleague understand how the application is working?
Even if you are in a company where the team is changing dynamically or if you are working on your application and at some point, you need to hire new teammates, in the first 2–3 weeks you need to have the onboarding process with them. Usually, you present the high-level business flow, you let him know where he/she can find the solution and what technologies you use and after that, you continue to work on your business. After a while, the new colleague starts taking tasks, but you discover that the tasks are taking too long or the code doesn’t do the things that it is supposed to do, and you start asking why. The most common problem that I saw over my career is that they didn’t understand correctly what the application does, both at the business level and also at a technical level. Even at a technical level, let’s say we should have a background, every application has a different code base, a different architecture, a different deployment method, and even a different team flow, which at the beginning can be very confusing.
It is understandable that you don’t have too much time to explain the entire application (and also you won’t be able to remember all the details) because you might have a lot of meetings, or you need to coordinate the team, or you have your own tasks to deal with etc. But here you can come up with the documentation and the diagrams or all the necessary resources to be sure that the new hire can have all that he needs to understand what is to be done.
Bonus motive to use the documentation
Many times when you need to implement something new, you think that it is enough to just write the documentation or a response from Stack Overflow, and by miracle, you realize it’s very easy, and you know exactly how to do it. But when you start writing the implementation you don’t know anything anymore, and also you need to do extra modifications to be compliant with your application. My advice after making the same mistakes is to create a small proof of concept where you can play with different configurations, different situations that are compliant with your solution. By doing this, you will understand the concept behind the scene, and also you can extract only the things that you need without overloading the code.
Don’t forget to read the first two articles from the series ‘7 mistakes’ and ‘Don’t start writing code’, where you can find more mistakes that I made and that maybe will help you avoid them.