Importance of proper documentation in a project

In the tech industry, it’s not uncommon for developers to work on project maintenance. You could be asked to fix a few bugs in a system which is already in production and has a user base. Or to add new features, or to refactor. Sometimes, you’d even be asked to rewrite the whole project in a different language/framework. For all these, it’s very important to setup the existing code on your development machine, and understand it properly. And for this, you need proper documentation.

Most projects today have their own git repository. It’s very unlikely that a project is distributed within a team by copying it on to a storage device. Even your incomplete, two-year old pet projects are usually on GitHub. This means the projects have some sort of readme file. Well, they are not there for no reason, right?

Only a person who has experience in trying to setup a project written by somebody else will understand the importance of a readme file. Life becomes so much easier if there are instructions in such cases. Proper commands, the necessity of using that third-party library which has a funny and suspicious name, etc. could be included in the readme file. This especially helps if a person is new to the technology used for that project.

You must have realised by now that you already know these things, because you have read hundreds of posts that talk about the importance of having proper documentation.

Take the example of any open source project — small or big, popular or not. They all have readme files. Because it makes it easy for potential contributors to dive in. And just because your client’s project is not going to be open sourced doesn’t mean that it doesn’t need documentation. Suppose you leave the project for some reason, maybe you die. Some other developer has to deal with your code now. If you haven’t documented it, that person will curse you even though you are dead. Don’t let that happen.

This doesn’t stop at readme files. If your project is already on Git, that means there’s an option to setup a good wiki as well. Do that! You can discuss features there, maintain it like a journal so that it has all the information about a feature. Anybody with access to this wiki should be able to understand the feature clearly.

Next, comment your code. You already know this can’t be stressed enough. Comment anywhere and everywhere you think it’s needed. For example, comment on why you are initialising a variable to one instead of zero or null, why you are using a while loop instead of a for loop. Things like this might seem trivial when you are working under a deadline, but this will mean a lot to the person coming after you to clean up your mess, or to add to it.

For almost all popular languages and frameworks, there are packages that automate most of the documenting efforts. There are IDEs which generate a minimum amount of documentation for each method and file you write. This is better than having no documentation at all! Once you are done writing a new feature, take an hour and document the final code before pushing it to the repo so that it’s always there.

Being a developer myself, I know it’s frustrating to document. Some people will dismiss this saying good code doesn’t need documentation. Well, if this is true, your code is not good, because your code needs documentation. All code needs documentation.

There is actually a benefit for you in the long run. When you move out of a project, people coming in will not bug you by emailing or calling you at ungodly hours. They’ll not find the need to disturb you at all. Your life becomes peaceful. Makes sense, right?

I’ll end this by confessing that even I haven’t been following this properly. Only when I faced all these issues recently did I realise the importance. Give it a try, and maybe, it’ll not be that bad!