A Magic To Highly Efficient Coding Practices

Yes, I believe there is magic to reach a state of high efficiency*.

The magic is documentation. It makes things clearer, which brings efficiency. You might think that it doesn’t work for startups, I believe it also works for startups.

There are some counterarguments to documentation, let’s go over them.

We don’t have time for documentation

To be honest, I am not a guy who wants to make things harder. Instead, I love the shortcuts. I also love efficiency. If there is an easy way of doing things, I would find that way more aesthetic.

Documentation allows you to think about the project. Instead of having thoughts, you have a solid manifestation when you document it. So you will have a better chance to analyze the bottlenecks and pitfalls. On top of that, you will have the opportunity to share your manifestation with people around you to reinforce your manifestation.

Thus, documentation creates extra time for you. Because

  1. You are not stuck to a problem since you get a comment from your partner.
  2. You don’t create a solution for a wrong problem since your client shows you the correct need.
  3. You don’t try to find a solution when you are in the middle of coding to find a path to a solution, since you already visualize your solution and decide on a path that leads you to the solution.

Documentation slows down the process

Documentation is the solid version of thoughts in your mind. By documenting your thoughts, you give shape to them so that it is open to tailoring. Yes, you need to write the document which might mean a 30 minutes time loss, but in reality, it allows you to test your highest speed in action by clearing your windshield.

Documentation brings a lot of meetings which take a lot of time so we can’t start what we need to do

There is no necessity of creating a complete and fully covered document at once. It can be an incrementally written piece of work. Just write your thoughts, set a quick 5–10 mins meeting, or send an email to the participants. It won’t take an hour to come to a consensus. If it takes more time than that, you better do it documented because it means you folks are not in a consensus and it is better to discuss the conflicts before diving more into it.

No one needs a document

Everybody needs it, let’s say you are a developer. It is always good to have a clear purpose. Let’s say you are leading the project, it is always good to have something written, so there will be no excuse for misunderstanding. Let’s say you are not very familiar with the project, maybe you just start working on the project, take a couple of minutes to go over some documents to have an understanding of the project. It is easy to find many more use cases that document becomes handy.

Enough documentation has a vital role in engineering. I have 14+ years of engineering experience. My first 10 years of experience was in the defense industry. I am familiar with the waterfall methodology. You don’t have much chance of doing things wrong in the waterfall, but I can’t say the same for other mostly used methodologies.

You might end up doing the same project multiple times with different solutions. You might face a problem after spending a lot of energy just because nobody foresees what is coming and your project leader might say “ let me think on it” and in 10 seconds, he might say “ let’s do it this way” and repeat this interaction multiple times in an unorganized way, at some point you might find yourself in a position that you don’t remember why you do things that way.

Documentation is very important for me, I do not prefer to take the risk of losing time/energy by not creating documentation.

*: By efficiency, what I mean is doing something in the best way to the current knowledge. Such that, it is highly not probable for you to do it in a better way.

Engineer, husband, father. 14+ years of professional experience. Mostly worked on research projects.