When I was in elementary school, one of the phrases I hated the most was when the teacher would say, “Show your work.”
What did that mean? Was I supposed to write down the voices in my head, the ones that told me that 2+2=4? How could I show something that was memorized? It was not until much later in my life that I better understood what was meant by Show Your Work. It certainly would have helped me if someone had explained a little better back then.
If you have a simple math problem like this:
124
+ 456
-------
We could write down:
4+6 = 10 (so write down the zero and carry the “one” to the next column left)
[1+2=3] (add the carried “one”)
3+5 = 8 (next digit)
1+4 = 5 (most significant digit)
Or we could just show the leftward progression of our addition, noting any carries from one column to the next:
11+2 4
+ 4 5 6
-------
5 8 0
Sometimes in life, we don’t have the time or energy to completely document all of our work as in the first example. But we certainly can use a short form in the second example. That second example is likely good enough for someone else to check. If I incorrectly forgot to carry the one and wrote the answer as 570, it would be apparent that either I forgot to add that carried digit OR I made a basic math mistake of adding 5 plus 3 and somehow got 7. It would certainly be easier to identify the location of a mistake in the first example.
My general guideline has become that your documentation (also known as “show your work”) should be good enough for a third party (someone not involved in the original work) to reproduce or check your steps. That means that you should make every effort to increase clarity in your writing. Avoid indefinite references. This is discussed in considerable detail in Chapter 2 of An Engineer’s Guide to Solving Problems. It is also a key part of the Problem Solving Template, available in the Free Stuff files section of this website.
Let me share a short story about how clear documentation allows a third-party to check your work.
Once upon a time, there was an engineering team trying to deliver a video Set-Top-Box design. The analog video output of the prototypes were showing too little chrominance (chroma) subcarrier signal. The fix should have been trivial, since the main chipset had a register which could control the amplitude of the chroma signal.
This is where the story became confusing. The software (driver) for the chipset was controlled by a remote software team, far from the primary engineering team, and far from the chipset vendor’s hardware teams. When an increase in chroma level was requested, the next iteration of software showed far too high of chroma signal level. The teams went back and forth requesting and attempting a fix. The result always showed either too high or too low of a chroma level.
Sadly, the back-and-forth oscillation went on through many weeks and attempts at new driver code.
Finally, the question was asked, “Can the software team see the result of the change they are making?” Their answer was surprising: “No, they have no equipment or instruments to show them the video output characteristics.”
That surprising answer turned the conversation towards the actual value the software folks were making in the register. They responded that they had tried 0x67, 0x68, 0x69, 0x70, and 0x71 and none of these values made the hardware folks happy, who reported chroma was either too low or too high.
Eventually, one bright sales engineer monitoring the email thread jumped in. He asked, “Are those really hex values you are programming, or have you just written them as hexadecimal out of habit?”
As you have probably figured out already, the programmers had correctly noted that the values were in hexadecimal, but they were counting up as if the value were DECIMAL (67, 68, 69, 70, and 71). Doh! There are 6 additional values between 0x69 and 0x70 (0x6A, 0x6B, 0x6C, 0x6D, 0x6E, and 0x6F). A value of 0x6A turned out to give the slight increase needed and the problem was finally solved.
Unfortunately, this process cost too many weeks and a ridiculous amount of manpower. Had the software team been properly equipped, they might have been able to identify their mistake earlier. But perhaps that still would not have helped, if they continued to be blind to their simple mistake of counting up in decimal, when working in hexadecimal (base 16).
Ultimately, it was the process of them showing their work in an email that allowed a third party to quickly and easily identify the mistake.
Although the many engineers in this story went on to solve other, bigger problems, this mistake lived un-happily ever after in their memories.