I have a problem. The canooter valve has gotten stuck from a flux-capacitor overload. Because of this, a server’s warp-drive has gone critical. We have received almost 50 calls so far that user’s plasma-coils are popping. Everyone is looking to me to fix it. What am I to do?
I do like every other great technician/engineer does. We research. First, let’s check if we’ve seen this before. Login to ticketing system. Check. Navigate to solutions database. Check. Search for “canooter valve plasma coil”. 1 result:
“Canooter valve frozen. Reset the plasma coil. Popping stopped”
Oh, yeah. That’s helpful. After spending 45 seconds wasting time thinking what I’m going to do if I ever find the person that wrote this “very well-written solution”, I decide to start troubleshooting. Starting from what I know is working, I work my way backwards until my testing fails. Once the failure is found, review and test the failed “component” and repair/replace.
Done! Problem is solved. 2 hours of work completed. At this time, I start wondering how much time others have spent fixing this exact same problem. If this has occurred 4 times, and it took me 2 hours to fix, that means a minimum of 8 hours has been wasted on fixing a problem that only took 1 hour 50 minutes to find, and 10 minutes to fix. How can we work more efficiently?
Solutions are not meant to be “Documentation”. That is to say, that Solutions explain the “How-To” of degraded components, while Documentation explains the “What and Why”. Here is a short guide to writing good solutions, which I wrote for my team. This is not, by any means, an authoritative or detailed guide explaining every detail and aspect of your writing. Instead, it’s meant to act as a guide or refresher for you or your team to follow.
Are there other items that you think are important? Why and Why not?