Have you ever wondered why or how so much time can be wasted performing what should have been a simple task? I recently encountered a situation that could easily have been avoided if the information I received provided a little more detail including tips and traps to avoid.
I’m currently writing a database application in Python that will solicit data from an SQL database . The unexpected work “stoppage” occurred as I was testing a database module that I was planning to use.
I continued to be greeted by errors every time I attempted to run a small script written specifically to test the module and it’s various functions. I followed the step by step instructions as provided in the core documentation and checked, double checked, and triple checked my code.
I determined that I can’t be the only person to ever experience this problem and turned to Google in search of answers. After a lot of research and reading, I finally found an explanation related to the error I was experiencing and it was one that also made sense:
Files cannot be written to a drive’s root directory.
When I reviewed the instructions again, I realized that writing to the root directory could be a possible source of error. The instruction and examples I was using to model my code wrote the file to a subdirectory several levels down from the root. I initially decided to write a file to the root directory where I could easily find it as I didn’t want to have to traverse the hierarchy of the drive’s directory structure for a “simple” API test.
Although I thought I was following the directions to the letter – step by step – I actually introduced the potential for error by attempting to write the file to the root directory.
To be clear, the information accompanying the module did not explicitly state that files could not be written to the root directory. Could it be that the author of the module never experienced the error because they wrote the file to a subdirectory several levels down from the root? Or, could it be that the author just assumed that we would “know better”
Thankfully, the code executed successfully when I created a subdirectory at least one level down from the root and attempted to write the test file to it accordingly.
Lesson Learned
I personally believe that you can’t be too thorough. I would rather have someone complain that they “get it”, as opposed to not giving enough information and assuming they did. In this case I lost a lot of time if the presumption was that “I should’ve known”.
No matter how hard we try, it seems that you can’t provide enough information or instruction to prevent “users” or programmers alike from doing the right things in ways we least expected them to. Assuring that your code will execute without flaw is challenging enough. Assuring that a programmer follows best practices when implementing the code makes the process even more complicated.
As an aside, one of my pet peeves is the daily barrage of “App Updates” where the primary reason for updating is “Bug fixes and improvements”.
The authors of the module may not have considered all of the “possibilities” that others may attempt for their specific implementation. If they did discover this anomaly, then it should have been documented and duly noted.
… For Dummies
More often we tend to present the “solution that works” without due attention to the potential sources of error, side effects, and / or consequences of failing to follow the instructions as written.
One of the reasons I recommend and give preference to “… For Dummies” books is the inclusion of the “Warning”, “Tip”, and “Remember” icons used to call attention to details or specific information for the topic at hand. Even the “Foolish Assumptions” explicitly clarify the pre-requisite knowledge required before reading the book.
Chaos in Paradise – The Garden of Eden
The temptation to defy instructions, regardless of the consequences, prevails throughout history and dates back to the Garden of Eden. Even then there was chaos in paradise when the notice to evict was given.
In a perfect world, everything works as intended. Unfortunately, reality gives us cause to consider all of the possible side effects, nuances, traps, and consequences. For this reason, everything is in a continual state of improvement.
There’s always a better way and more than one solution!
Why this matters
If I knew that writing a test file to the root directory would cause the module to fail, I would’ve changed my code to write it to a subdirectory. I could have saved myself a few hours of time and my confidence in the solution provided by the module would have remained strong. The continual errors gave me cause to challenge the choice I made and to consider whether I should look for an alternative solution.
How much time do we lose in our day to day operations because people are deviating from the “working solution” with every intention of saving time or attempting to be more efficient? The answer is as varied as the number of people involved.
Your feedback matters
If you have any comments, questions, or topics you would like us to address, please feel free to leave your comment in the space below or email us at redge@leanexecution.ca or redge@versalytics.com. We look forward to hearing from you and thank you for visiting.
Until Next Time – STAY lean!
[twitter-follow screen_name=’Versalytics’ show_count=’yes’]
