Most IT professionals will agree that good documentation is important to maintaining stable, easily manageable infrastructure. However, many are so busy and rushed that they put off or completely ignore documentation because of all the pressing fires they feel pressured to stamp out. They rush from one fire to the next, swatting at the flames, throwing blankets on the fire, stamping with their feet, and putting out most of the fire. But they leave a few embers glowing or small flames still flickering – no documentation – and run to the next major fire and start putting it out. Their last fire smolders and simmers, ready to break out into a brand new fire at a moment’s notice. This is called technical debt.
Just like paying down a mountain of credit card debt is really hard, paying down technical debt is just as hard, if not even more challenging. Typically the choice to start paying down debt is not just the IT pro’s decision. It is the decision of their manager and even upper management. Sometimes business try to run and change so fast, they are in a rush to move to the next project or initiative and they don’t leave the IT pro time to pay down the technical debt (documentation). Managers may be under pressure to fix the next big problem, so pressure the IT pro take shortcuts and just get the current fire under control and go work on the next problem, leaving the smoldering embers of technical debt in their wake.
Just like credit card debt, at some point you either decide to pay off the debt and move to a debt-free life of less pressure and problems, or you continue your indebtedness indefinitely and suffer the consequences knowing the debt must be paid off at some point, or you file for bankruptcy and discharge the debt.
This cycle of technical debt is just like the cycle of credit card debt. It can spiral out of control and cause many problems – in your personal life with credit card debt and in business/IT life with technical debt.
As a high school and college student, I worked for my dad in his swimming pool construction business. My dad was a stickler for doing the job right. While he was a fairly simple man in many ways, he was always focused on making sure his customers were happy. And part of that was making sure all the tools were picked up each night after work, the trucks were kept washed and clean, we had clean uniforms to wear each day, the maintenance was kept current on the trucks and heavy equipment, and the job was cleaned up when we were done. He would pound into our heads “The job is not done until the tools are put away and the workplace is picked up.” And he meant every single night. He would make sure he budgeted in the time each day to stock the trucks and check the oil each morning before heading out, and to pick up each evening after the workday was complete. My dad never heard of “technical debt” but he would know exactly what I was talking about if he were alive today.
How do we pay down technical debt?
But how do you get out of this technical debt? Just like you do with credit card debt. You have to make a decision “enough is enough, I am going to start paying more on my credit card than I borrow each month until I get it paid off”. Same with technical debt. You as both an IT professional and as an organization have to decide “I am going to do the job right and complete this job before I move on to the next fire.” And doing the job right means writing or updating the documentation so that you or others following behind you know what was done and can follow your logic.
One way to pay down technical debt is to make a personal commit to document what you do, each and every time. Nobody likes writing documentation. It seems time would be better spent fixing actual live problems, not documenting the problem you just fixed. But skipping documentation is just like leaving the last job without picking up your tools, or putting out a fire without making sure all the embers are out and the flames are not waiting to burst into a new fire. Even if your organization or boss is pressuring you to get to the next urgent thing, you can still force yourself to complete the documentation first. Write down those IP address changes. Completely fill out the work ticket with details of what you did. Update your company Wiki or knowledgeable with the correct changes. Complete the change logs with thorough, complete notes that can be easily understood by the next IT pro that comes in behind you. Thoroughly comment the code you are writing.
Sure, your boss might be irritated that you are taking a bit longer than usual to complete the job. But you can control that. YOU can decide to take a few extra minutes to complete the job rather than taking on more technical debt.
Work on projects that automate manual tasks
Often we are so busy doing our daily work, putting out the brush fires that keep popping up, we don’t take the time to work on high-payback internal IT projects, such as automating our manual daily tasks. Allocate an hour or so per week to think about tasks you do on a regular basis, and try and find a way to automate that tasks. That could be scripts – not ideal. Or it could be implementing “infrastructure as code”, something like Ansible, a tool that allows you to include your infrastructure setup with your code so that it goes through the same revision control systems as your normal code, and pushed out automatically when it is approved. Develop automated development pipelines that runs your unit tests each time code is committed to your repository. This can speed the development and deployment of software and help limit mistakes. Use API hooks into your network environment to manage and control your network on a large scale, right from within your development and change-control environment. These tasks are hard, and often the reason they are put off until “later”, but they can have an oversized impact on the productivity of your IT organization and significantly slow and even reduce the buildup of technical debt.