Technical Debt

I have been architecting, designing, documenting from an engineering point of view, implementing, and testing software products and services for a few decades. Many years ago, working for a Fortune 500, I was troubled by the practices used to develop software. It seems that there had to be better ways to get from requirements to products and services. That induced me to read books and papers and take several college courses in order to satisfy my curiosity and be able to apply and create better ways.

In my opinion, the way to develop software is in a cycle of nine months. Each cycle contains the well know phases of architecting, designing, documenting, implementing, testing and delivering to potential customers / users the software. Once in their hands, one should monitor and collect feedback in order to use it to improve the product / service. I called my idea Cyclic Development Process (CDP for short).

One of the key aspects, which I have used for decades is to create a reduce set of useful technical documentation. It has been said that if you cannot describe something, you do not know the subject well. We also know the saying that a picture is worth a thousand words. Putting these two concepts together, you should be able to produce short, simple to use documentation for any software product.

In Agile it is considered that the software is the only thing of value. Documentation is considered as a useless artifact. I was one asked if I would start a software development project without having requirements. My answer was simple and short; no I would not do that. The issue with such approach is equivalent to embarking on a trip (not a journey) without a map or a schedule. If the idea is just to tinker and wish for the best, then go for it. I always document before I start implementation. When you sit down and draw a diagram (I started using MacDraw on an Apple Macintosh but for a decade or more had to switch to Microsoft Visio running on a Windows machines), you have time to think about what needs to be done. Chances are that you will never get it right the first time. This is why all software projects should be done in three phases, each containing all the basic steps. The difference is in the emphasis put on each. On the first phase emphasis is on architecture and design. On the last phase it switches to coding and testing.

So what is technical debt? Technical is a concept in software engineering that reflects the implied cost of additional rework caused by choosing an easy solution now instead of using a better approach that would take more time but will produce a much better product. I am not sure who coined the phrase. What is important is to understand the ramifications of a project that is not well thought out and lacks the application of software engineering principles.

We humans are quite complex. It is impossible to get two individuals that are the same. We use natural language to communicate with each other. Computers use specially designed languages that central processing units (CPUs) understand so they are able to perfectly follow what programmers tell the computer to do. The issue is that in most cases, programmers do not know and misinterpret what needs to be done so they can code the instructions for computers.

It all starts with a reduced set of technical documents (i.e., SRS (Software Requirements Specification), a SDD (Software Design Description) and a STD (Software Test Description)) that must be kept up to date as part of the life cycle of the product. By keeping the number of documents low, the size of the documents short, using diagrams and not too many words (do not write Victorian Novels), developers in the team, new team members, managers and customers, are able to clearly understand how the system works. By doing so, development and testing time is greatly reduced.

We can now see why the analogy to a monetary debt was used. Today when we feel like purchasing a new vehicle, we have different ways to satisfy our need. We can save the moneys in advance and when we have the price of the vehicle plus taxes, licensing and delivery fees, purchase it from a dealership. Most people use credit. We put a down payment, pick up the car, and during the next three to seven years (yes companies are financing cars for seven years), we have to pay about double the price of the vehicle. We accrued debt, which allow us to have the car quicker. In software development the analogy is very close. We have to develop software for a product or system and instead of taking the proper time (which in my opinion should be about 9 months) to properly develop and document the software with the proper number of features. If nine months is not enough, then the project can continue for several months or years using the same technique employed during the first nine months.

As usual, tools and ideas are always popping out. We need to recall that there is no silver bullet for software development. We need to automate the process as much as we can. There are many tools that help us architect, design, implement, test, deploy and monitor software. You need to monitor the performance of your product / service. We know that we cannot manage what we cannot measure.

In the past few years I have been interested and have worked with micro services. As usual I have read several books on the subject. It seems to me that the same software engineering principles, most of which have been around for several decades, apply to what we call today the latest technologies. Decades ago we err in producing large documents which became obsolete before they were completed, to not generating documentation at all, to generating and maintaining a short and reduce set of technical documents.

Always try to automate tasks when possible, making sure you do not induce complexity and mistakes. I have seen how mistakes have eliminated desired features in existing tools.

Happy software development;


Follow me on Twitter: @john_canessa







Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.