Recently Xiu Lincheng and I were discussing a technical problem. I had made my usual comment about needing to get this problem documented, when he said, “No Bob, you are wrong.”
This set me back a few steps, since I take Document or Die and Write It Down as immutable truths. Then he said the most amazing thing:
“You have it backwards: you should do what you wrote, instead of writing what you did.”
What Lincheng meant has become a new problem-solving guidepost for me.
He showed me exactly what he was describing.
He was debugging a very complex RF hardware-software setup. He needed to issue some complicated commands to the software subsystem, which would configure the hardware to tune and demodulate a special test signal. The test equipment also required complex configuration commands.
The steps he took were to open a basic text editor. He then typed a few comments to describe the system connection (setup) and the intention (plan) of the tests. Then he typed each command he believed that the device-under-test and the test equipment would need. A quick Save command made sure he would not lose this work.
Then, step-by-step, he copy-pasted each command from the text file into the device-under-test command interface and into the test equipment command interface. The device-under-test began to transmit some expected signals (as confirmed on an oscilloscope) and then the test equipment showed a reasonable, believable, and repeatable result.
This process has an amazing benefit: the documentation was being checked for absolute accuracy by acting as the source material for each command. Said another way, the documentation was being verified by the process of doing the test.
At one point, he found an error. The text file was quickly corrected and saved again. The test command sequence was checked again from the beginning.
If one command needed several variations to exercise the hardware, each variation was recorded in that text file. Sometimes notes were added to explain a sequence or intention.
The brilliance of Lincheng’s strategy was that when he completed the test, he was already done capturing the documentation required for other folks to duplicate his work. Furthermore, his documentation was assured to be correct (or at least was guaranteed to match the steps he had taken).
Contrast this to the traditional approach, where an engineer is convinced he/she will always remember what they did, and then sits down, writing a test procedure for other folks to follow. But human memory and typing are often weaker than we wish to admit, so the outcome of the traditional approach often captures these later errors. Then, this bad documentation causes the next engineer to make a mistake that was not part of the original test.
One way of viewing this strategy is to see it as a logical extension of the Plan-Do-Check-Adjust quality process (also sometimes called the Deming Wheel). By doing detailed documentation FIRST, and making that documentation part of your plan, you are assuring that your results are repeatable. You don’t have to worry if the Check phase produces corrections, because you will Adjust (fix) your documentation (Plan) before you start the next Check attempt.
Even though your debug and test might not have similar software/hardware setup as described above, this strategy can be applied to many engineering tasks. If you create detailed documentation, and then execute your tasks against that documentation, you will complete your tasks with valid records available (immediately) for other folks to use. Errors and mistakes must be corrected as they are found and then the cycle repeats.
Your process should be designed to execute the steps from your documentation, instead of trying to later document the steps (you think) that you took.
I wish I had learned this idea many decades ago. It would have saved me a lot of time and trouble.
Please: Do what you wrote, instead of writing what you did.