So you have just developed this new feature and your application can calculate things. Some very, very important things. Business people are happy. …at least for few days. Then they start asking questions. They want to know how the numbers you give were calculated.

This is a recurring pattern that I observe.

For the first time it happened to me few years ago. Back then I was working on some fancy system which allowed to calculate bonuses for sales of financial products. Oh my gosh, how many (stupid) rules where there! And they were time-bound and they changed oh-so-very-often. Marketing people were adding new rules (new bonuses) for different products on daily basis.

The software used Drools (ver. 2.0 if I remember correctly) and had a nice GUI so users could create quite sophisticated rules by clicking. It worked like a charm.

…and then they started asking questions.

Of course they wanted to know! After all, it was all about the money. And every salesrep had his/her own Excel with calculation. And whenever our system said they should get less money than what their excel calculated then they wanted to know how the hell we calculated our result.

An interesting thing is, that they were always wrong. They made mistakes. They always did. They forgot some rule was no longer holding when they made a sale. Or that some other rule was only applicable when sales was over 20k. Or that they needed to sell 3 items of certain type and they sold only 2. Really, this is the kind of mistakes they made.
And we never made such mistakes. We calculated money without emotions. Our answers were right. But it was not enough.

Lesson learned: it is not a valid result unless you can explain to users why it is valid.

So after having our perfect system working perfectly we spent few more days on making it output not only the final result but also how it was achieved. As far as I remember, we ended up with list of all rules with green dash (rule applied) or red tick (not applied) next to each rule. It was enough to radically cut down number of questions.

After this I got a little bit wiser and now, whenever I feel users might be interested in learning about the reasoning behind the final result, I try to think about such features from the very beginning (no, it is not a YAGNI, cause you definitely gonna need it).
And the thing is that often it doesn’t have to be anything fancy. Few log entries with crucial data used for calculation might be enough. If someone asks all you have to do is to find the appropriate log lines. Once you get tired with logs browsing you can think about exposing this data via some API or even GUI. But this can wait.

…and if you do not implement anything to explain the result then you will spend your time writing (No)SQL queries so that you can understand why the answer you gave to your user was 44. Good luck!