Category: Building Software

One of the things I see most often plague an organization is the lack of documentation and reproducible builds. That has not been historically an issue. However, when the downsizing and rightsizing of the turn of the century kicked in, many developers moved on or were let go. While those were not bad business decisions, they did allow some critical knowledge to walk out the door. I have come across several organizations post the COVID lockdown that took too many years away from maintaining their systems. They have paid the price for a lack of documentation and reproducible builds. These are two things that are often viewed as academic but are actually critical to the longevity of a solution.

Why Bother With Documentation And Reproducible Builds?

If there is a winner for the most common rookie mistake in software development, then this pair most likely tie. I cannot count how often a young software shop changed code on production systems to “save time” or skipped documentation because the code was “easy to read” or intuitive. While there are arguments for these measures, they miss out on the long-term value of a short-term fix. Even worse, an application is useless if we can’t build and deploy it. Those steps almost always require both documentation and reproducible builds.

There are some very smart technical people in the world. However, even the smartest can look at a solution and be completely perplexed. There are so many moving parts in most modern solutions it can take days or weeks to get an idea of what is used to create a solution. We need documentation, at least, to help us get an idea of what a solution is made of and the mindset of the developers. This is even more essential to taking over a solution that was written with technology that is no longer viable.

The Skip A Version Approach

In the early days of software development, there were many companies that embraced the skip-a-version approach to upgrades. This smart compromise kept the company current without getting stuck in an endless upgrade cycle. It was easy to get into a rut where upgrades came so fast it felt like you were always learning a new system. That frequency often eliminated productivity gains and frustrated users. We still can see this challenge occur when software is updated “too often” and users are just getting comfortable with a version when an update comes out. That is why some people turn off automatic software updates and seem far more productive than those on the leading edge.

While a version or two can be a smart decision, software often changes dramatically over a few versions. There also is a challenge of getting old versions that become more of an issue as software ages out of use. Sometimes, releases like Windows XP stick around for several years. However, that is the outlier and not the norm. Software can be almost unobtainable a few years after release in some cases. That can make it almost impossible to build or update that custom solution you paid so much to build a few years ago.

Provide A Regular Check-In

Disaster recovery plans critical tools like fire extinguishers should be tested periodically. When you fail to ensure they are current you leave yourself open to experiencing them failing at the worst time. Software and technical solutions are very similar to this. You need to periodically ensure they are current enough to be ahead of disappearing technology. Operating systems are a very common example of this. Your application may run fine on a specific operating system. However, that OS will age and eventually become unsupported. That alone is a reason to upgrade your system. Even worse, there are things that can happen that make OS sunsetting look like a walk in the park.

Many solutions are created on a language or framework that has specific version requirements. As the language and frameworks age they may or may not be as compatible. Your solution may require some libraries to be updated. On the other hand, the libraries required may no longer be available. Technologies fade and die. That can put you in a situation where your current application no longer works and you have no way forward other than creating it from scratch.

I have come across more than a few examples of this. In some cases, the original documentation and source code was lost. That caused the company to have to re-imagine the solution based on how they remembered it working. If that sounds difficult then you are correct. It is better to forget the old solution existed in that case as you end up second guessing every feature and how it needs to be implemented.

How Did I Do That?

Have you ever looked back at a task from months or years ago and asked yourself how you did it? The forgotten aspects may be a critical step or piece of information. This problem is why we take notes. We want a way to remind ourself of what we did and how we did it. Documentation and reproducible builds provide a way to take detailed notes for a developer to use in learning how another developer got the job done. The end product is almost never enough. There are hidden details in the code and even the build process. Deciphering these details can cost even a seasoned developer weeks of trial and error. Sometimes the original approach is lost just like dead languages or other bits of knowledge that can not be recovered.

Next Steps

Now that you are sufficiently warned, you are asking yourself what you can do to ensure that documentation and reproducible builds have been adequately created or provided for. The simplest solution is to ask for them from your developer or team. They will either explain why those do not exist or point you to their answer. For the non-technical among us, there are a few questions you can ask to help vet the documentation and build process without learning the system inside and out.

• Ask how someone can access the source code. You might even request a copy to store somewhere safe.
• Look for a list of logins, passwords, and server details. These should include ways to access the server as well.
• Verify there are steps to build the solution documented somewhere. You might even attempt them or hire a third party to do so.
• Request the developer or team to do a “clean install” or build. Things can be forgotten so forcing the developers to build the solution on another machine can highlight the gaps.
• Ensure a list of technical details are provided. This includes languages used, version numbers, libraries, frameworks, etc. These can be critical to staying legal and avoiding surprise license issues or costs.

About RB Consulting

Feel free to schedule a time to discuss your next project with us and see if we might be the perfect partner for you. We take these relationships seriously and are happy to point you in the right direction if we are not a good fit. Years of being on both sides of these relationships have taught us a lot. That initial call is free, and there are no obligations. You have nothing to lose. 

Our experience has taught us a lot about the pitfalls and challenges of custom software. Likewise, we have an e-book that can help you explore all the steps in building software, including a few templates. However, we ask that you share an e-mail address so we can send you a copy. We will add you to our monthly newsletter, but you can unsubscribe anytime. Your data is not shared with anyone else. Learn more about our book here.