Be careful what you say. You may give someone just enough information to be dangerous.

As a person in a career field that requires the slightest detail to be fleshed out and dealt with at a unit level, I tend to speak in the same manner. Like lawyers, precision is the key when it comes to programmers. Unlike lawyers, the actual implementation of the letter of the “contract” (in this case the “program”) is never up for debate. Either x = 5, or it does not.

It is therefore very easy to give people enough information to then make flawed conclusions. Here is an example:

My team and I developed a complicated software system consisting of a website, APIs, and a batch program. The website was very robust, but the real work in the system came in the form of batch processes that ran and kept it all moving along in the background. These processes were fed data from the database, and the database gained records for the batch process to act upon from one of the websites, or the APIs.

During a status meeting we made the mistake of only glazing over the system’s architecture, and when a question was asked we mentioned that “the batch takes care of that.” No real explanation of exactly what the batch does, or for which functions in the system it was responsible.

At this time, the marvel that was the “batch” became the cog that affected everything. Questions from then on started with “I think the batch did x” or “Did the batch complete the y” instead of simply communicating the symptoms of the problem (or NOT problem most of the time) so that it could be dealt with.

It started as an annoyance, with every question coming with the word “batch” attached. Then it became a joke. Our answer to everything was “I’ll check the batch”. Then it became a real irritation. If an image was not loading on the website, someone would ask “is the batch running”. This is not overstatement. This is really what happened.

We had issue tracking software, and that was the primary form of communication of bugs or issues to the team, but to really quash this we had to train ourselves and our users to communicate only the precise issues they were seeing rather than their opinion of the cause. It seems obvious now that we are doing this, but at the time we were not strictly enforcing a real issue reporting protocol.

Lessons learned:

  1. We needed to implement an issue reporting protocol and procedure, being very specific about what we wanted (and did not want) in the issue report.
  2. We needed to either
    1. Educate our stakeholders fully about the architecture so that they can use the proper terminology to communicate with us,
    2. Not mention a detail that we did not want thrown back at us, or
    3. Just bite our lips and keep it to ourselves when someone asks a question in a way that demonstrates their lack of knowledge about the system.

We are on a combination of all three (A, B, and C above), really. Those who need to know, get to know. The rest, no touching the secret sauce.

So, what are we doing here, by obfuscating the implementation? We are just trying to avoid the frustration of certain users sending you down the wrong path to troubleshooting. If someone tells you they think the batch is stopped and does not give you enough details to see they are full of it, you will tend to check the batch immediately, and when you get there and see that it is running, your eyes roll back in your head because you realize you’ve been led by someone who would have NO IDEA what the batch is into checking the batch!

On the flip side, you can’t just hide implementation for no reason. You look like a jerk if you just say “don’t worry about it, I got it” all of the time. Take the time to implement an issue reporting procedure that makes sense, and when education is required, give it.