Why Must You Document Solutions?

First, let me address the problem.

There are a lot of good practices that were created for a reason. Unfortunately, a lot of times that reason is lost over time, so the new generation is told that they have to do the documentation in this case but without telling them how it helps, how it works, what the benefits are, and what problems they prevent or what problems they solve. So they blindly do the things just because somebody told them to do it or they will have bad consequences.

With this piece of information lost, any person (I was one of them) will logically assume that it is not needed, that is a waste of time, or that it hurts more than it actually helps.

Others turn very orthodox and dogmatic. They are enforced no matter what and demand that it must be done because the rules say so. They do the things blindly with no reasons at all. This is also bad because they don’t actually solve or help what they were meant to. In some cases, maybe your circumstance doesn't need that good practice, so you are willing to do work for nothing.

Without knowing the reasons why it is important to do documentation, it is very easy to create bigger problems.

With any problem that you need to solve, you will begin to climb a learning curve, which will include a lot of trial and error until you figure out how to prevent and solve those problems. That is how good practices are born.

All the problems that you face when doing any type of work, somebody has already faced them, and somebody has already solved them. It is very rare that brand new problems happen. So it is always a good practice to look for how others have solved those problems.

There are a lot of reasons why we need to make documentation. I am going to address the more important ones.

Communication between people is a quite complex thing and more complex than it seems. One of the biggest problems that we need to solve in software development is doing what the client expects to fulfill their needs. There are no few times when the user/client says, "This is not what I asked for." Writing that on a document where both have a copy of the exact same requirement will avoid this and will put the responsibility on the person that failed to do his job. The client/user job is to be clear on what they need, and the developer job is to do exactly what it is asked (you can learn more in the book One Minute Manager on the One Minute Goals chapter).

Next, can you drive a car without a dashboard? You actually can, but it would be a lot more difficult if you don’t know what speed you are going, how much gas you have, or something that tells you that there is a problem with the engine. If the projects are the same and if everyone does their part on the documentation, it will be easier for the manager to make decisions. The project manager needs to manage things like time to deliver, the quality of the product, the budget of the project, and the resources allocated. That extra time to document what you do during the day helps with all of that.

When problems arise, it is needed to know what to do and to whom you need to reach for solutions. Otherwise, you will waste a lot of time, and in some cases, the problems get worse for not resolving them on time or for expecting or receiving an answer from the wrong person. If you don’t document the issues that need to be solved, they may never be solved at all and may be lost in a pile of work.

There are a lot more things that documentation helps with and that also prevents and solve problems, but as you can see, without a purpose, it is useless or it does more harm than good. Always ask yourself when facing these type of questions: "Why did somebody think this was a good idea?" "How is it used in other places?" "What problems are intended to be solved or prevented?" "Does that solution help me at all?"

If you like this post, let me know, and I will make a series of how you can document a project.