Loud Baking

Having worked by myself on the vast majority of my coding projects, I never realized the necessity of having lots of documentation. Good documentation takes time to write and time is something I happen to always be short on. I am not only talking about code commenting here, but rather all kinds of documentation: coding conventions, database structure, choice of configuration, etc.

When this project was started, I only had one other person involved in the coding part and it was mostly for some outside classes we needed. With the growing code needs (all the new features, etc.), I believed it would be wise to add a new person to the team. Given my past experience with site/script development, for which I had never planned to hand to other coders, I was expecting the worse when it comes to explaining all what the web application is about: features, users, structure, etc. It definitely always sounds much simpler when you are the author/creator, but when you are also the end-user, things become ridiculously easy to understand and put together - which is unfortunately not the case for someone that has never heard nor used of anything similar before.

Luckily, I had started this project with a different methodology than the ones before: cleaning and archiving my brain farts.

What is usually the planning period, drawing sketches, listing ideas, etc. became a more organized and time-consuming task. From there was born the idea of having this blog among other new things to do, like keeping a docs directory in the repository with everything from logo drafts to market terms’ definitions.

My expectations were quickly proven wrong. By putting together a couple of diagrams and some features’ documentation, I was able to quickly prepare my 90 minutes presentation! It covered all the work we do on search engines, from scraping to the data cleansing and storing. I limited it to search engines only so the information is better grasped and not just force-fed. Next time, I will explain the second part of the data scraping/cleansing/storing, before finally exposing the data mining and user interface of the web app.

Lesson of the day:

Taking some time to write extra documentation early on is key to successful team work and growing development needs. Making it part of your repository helps keeping track of researches and choices made, structure and configuration changes, terms’ definitions and market’s conventions - but most importantly, it allows new comers to better understand the code they will be working on.