Last week, I talked about Point-of-Need help as a way to put better help in your internally developed systems. This week, I want to cover a related topic.

Imagine this situation (for those of us that have been in IT for a while, we don’t have to imagine because we have lived it). An application gets written and implemented. Years go by. The people in the organization that set the requirements have moved on to other jobs. The developers have moved on. New people come into the organization and start using the software.

Now we have a situation where the following is true:

• The interior logic and calculations in the code are no longer well known.
• Users understand the software by the output, not by the design.
• The assumptions and decisions made by the organization when developers created the software are no longer known by the users, management, or the new developers.

The last point is the hard one. It leads the organization to no longer trust the software. What can we do about it?

Portions of this article are excerpts from my book, The I.T. Leaders’ Handbook, available in paperback and ebook from fine bookstores everywhere.

The simple answer is to make those assumptions and decisions more visible to the users. How do we do that? By creating “Show Your Work” (SYW) screens.

When we build software for our organization, we embed parts of the business process into the software. Over time, the reasons and assumptions for how the software works are lost. People don’t understand why the software does what it does. Inevitably, a situation pops up that the software wasn’t meant to handle. Instead of fixing the software, people start to go around the software.

Here is an example. A manufacturing company had an application to help with costs. As the experts left, people started treating its output as truth, not the guidance it was designed to be. When the new situation popped up, some enterprising finance person built a spreadsheet to calculate costs. This spreadsheet didn’t take all situations into account, but got the new situation right. A few years later, some were using the application, some where using the spreadsheet. No one really trusted either.

The problem wasn’t that the software was suddenly wrong, it still worked as designed. It wasn’t that the organization completely changed their costing methodology. It was that people no longer knew the assumptions and design of the software.

So what are Show-Your-Work screens? Do you remember back in school when the math teacher wanted you to show your work when doing a math problem? You couldn’t just write down the answer, you had to show the steps of how you got to the answer. This is the same thing.

Create screens that shows all the calculations and assumptions made at critical steps in applications. In our example above, put a SYW screen at the point where the cost is calculated. The SYW screen would show what fields were used as inputs, the actual math, and the decision tree. Make it all text, but do it in a way to copy/paste it into a spreadsheet. If there are any assumptions, list those on the screen. For example, if you skip part of the calculation for a certain product type, that should be listed.

SYW screens have many benefits.

• It can be used in testing to verify that the inputs, calculations, decisions, and assumptions are accurate. This can be a huge time saver.
• It provides ongoing assurance that the software is working as designed.
• When new people come in, they can look at it to understand how the software works.
• When the inevitable new situation comes up, it will be clear where the software needs to be changed. This helps users and developers alike.

Once you build an API library to support SYW screens, it won’t add much to the implementation costs. The benefits of knowing what the software does over the years make it worthwhile for IT and the organization.

Photo by Annie Spratt on Unsplash