Musings of a Developer

Many years working with IT in different business sectors using various technologies and tools, I have learnt an essential aspect of being a developer - ALWAYS WRITE A DESIGN DOCUMENT.

The telecommunication sector employed some really good process philosophies when it came to IT. There were designated teams responsible for tasks in their SDLC and the process was followed to the T. Business requirements looked at the big picture and the integration with other tools, it specified what was expected by the customers as the end result. The Development and the Testing teams would huddle in a room with the Business requirements engineer for an entire day understanding every aspect of what was expected. This was the time the Requirements team had to have all the answers for the Development team. The Development team and the Testing team would use the requirements as their bible and create their design documents and testing scenarios respectively. It was another pow-wow session when the Development team had to defend their document while the Requirements and the Testing team could interrogate. The same cycle followed for the testing document which was always right before user acceptance testing could commence. Every requirement was referenced in both the design and the testing documents. It worked well, it was thorough and allowed for quality code to be deployed into production but it was time consuming. This was the 90s.

The 2000s brought rapid development to the fore. No longer could the projects afford the luxury of day long closed door meetings between the various teams. The requirements stopped being thorough and became high level and the development tasks started to get outsourced. This meant that every member of the team was not on the same page when it came to understanding the functionality expected by the customer. Most worked in their own SILOS. The project management became the core aspect of making sure the requirements translated well into expected functionality being coordinated amongst various development groups by the project manager. During this era - projects could afford the luxury of time only for the management of the team.

The shift moved to faster ways of managing projects with the Agile methodology - while emphasis by the industry was on the project management aspect - the developers and testers were not provided the best practices handbook. It was left to each team on how the effort could be managed and tested. Design documents lost their relevance specially when the teams were outsourced as a result it was cheaper to just buy a new tool rather than try and maintain an older tool due to lack of documentation.

As I moved between different industries and through the different eras - I retained the process techniques I learnt early on in the 90s. I guess I was young and impressionable then. But it has always helped me understand the product I am designing, or developing or managing when I have the requirements as expectations or outcomes that the customer wants and then build the development tasks around them. Even though I was not required to create the design documents as a mandate - I maintained them for my own sanity. My design documents started becoming a handbook of the product. It included the requirements and the testing scenarios.

Allocating a few cycles from my schedule to write the document always allowed me to be focused and be clear on what was expected in the time frame. A few years later if I was still on the same project and some change was needed - these design documents served as my cheat sheets.

The wise always say - writing helps remember - and I saw that play out many times as a developer and a solution architect.