“command-blind” —Adj: Why you get stuck following instructions you find online.
command-blind: a condition that occurs when a person finds instructions to do a “thing” they want and find themselves unable to make sense of the messages or information being displayed when the output they see does not match what the instructions show.
You copied and pasted it exactly as it shows, but for some reason it doesn’t work for your project. You find yourself repeating steps and going in circles without making any progress. You have thirty tabs open trying to find the right words to describe the problem, and none of them offer any hope of a solution.
You are so locked into the instructions on StackOverflow that you fail to look outside single window or item you are paying attention to. Like a motorcyclist with target fixation staring at a tree they are trying to avoid and crashing directly into it… you’ve gone command-blind.
Usage: I was so command-blind that I didn’t realize all I had to do was resolve two diffs! Everything I was trying to find was there all along, d’oh!
I came up with the word command-blind the morning after a frustrating night of coding. Here’s the story of how I figured it out.
It’s 3:15am and I’m so fucking exhausted and frustrated. I’ve spent about six hours over two sessions and I’m not even a millimeter forward from where I started. Am I just too stupid to understand the instructions? This documentation doesn’t work… I’ve tried it three different ways, TWO times on two different days. Neither one worked and I feel like they both ran into the same issue. FUCK THIS THING! LKSD;LKADL;KAFDSLJKDFSJLK
OK. I’ve taken a 15 minute break and calmed down. The best thing to do now is document my problem so I can effectively ask for help. I want to make sure I’ve tried EVERY possible thing I can think of before I post an issue on Github.
At this point, I went to the Github repo for the project I was working on, and I opened a new issue. To document my step-by-step reproduction instructions I used a tool called asciinema that lets you record your terminal sessions. I was still command-blind to what the actual real problem was, but at least I could share what was happening.
Ok, cool. I can reproduce the issue, and I’ve found a way to show the maintainers of this project exactly the issues I’m running into. I documented the one way it didn’t work… now let’s document the other way too! Surely these informative videos I’m producing will help reveal the flaws in their documentation!
Now I had not only manually typed and executed the commands myself a handful of times to perfect the videos I was recording, I’d also re-watched the videos a few times too during this process.
Wait, reviewing what I’m doing has shown me something new! I’ve stopped being a narrowly focused driver who had to pay attention to only what was visible on the road directly ahead, and now I can be a passenger who can look at all the other things the driver could not afford to spend precious mental effort on.
This is when and where the lightbulb in my head finally turned on.
Re-watching the videos I slowly began to notice that the “errors” I was seeing were telling me that the cherry-pick could not continue because there were two files that had changes from two places. Suddenly the words in the message I’d been command-blind to were clear as day. To resolve the issue I had to mentally leave the terminal window and go look at something else (the code!). I was so command-blind in following the instructions that I’d found that I was oblivious to the fact what I was seeing was in fact NOT an error. It was just git telling me I had to resolve two diffs. Over the years I have read hundreds of git diff messages and accurately fixed the problem at hand, but for whatever reason this basic task had eluded me till now.
I was too reliant on the instructions I read on a webpage and my personal git habits that when they differed from what I am used to my brain immediately complained and got mad when the result in my terminal window wasn’t exactly what the article showed.
Fret not though, for we are all human and prone to this behavior whether we like to admit it or not. You are not an idiot. This behavior is not unique to you! Accept that it’s ok to make this mistake, don’t beat yourself up over it, and most importantly resolve to identify when it happens in the future so you can overcome it.
For more info on identifying your own behaviors that you don’t even realize you are doing, check out this amazing short podcast by David McRaney about narrative bias and how the human mind rationalizes things. It’s a great insight into how we all do things we don’t realize, and that watching that same behavior in others helps you with introspection about the fact that you might be doing it too.
Freeing yourself from the mental pitfall I’m describing with being command-blind transcends programming as well; you don’t have to be using fancy programs or even computers, you just need to be able to recognize these three things:
- When you get stuck
- That you need to ask for help
- Most importantly, when you are becoming mentally frustrated
When you find yourself checking all three boxes, the best thing to do is to walk away from the problem for a little bit.
Recompose yourself, and do whatever it takes to return to the problem with a calm mental state. If you are still stuck after returning, get a second pair of eyes on the problem and repeat the process till you figure it out. Do not wait three days to ask for help… if you spend more than 15 minutes after coming back to a problem and are still drawing a blank, this is the right time to seek a second pair of eyes or a rubber duck.
So back to the problem that I had and the point of this article. In the beginning, I was convinced that the documentation was inadequate, and that the problem was a lack of clarity and specificity in the steps. After some time to marinate on the subject, I’ve come to the conclusion that MY PROBLEM (not the projects) was simply that they are using a git strategy I was unfamiliar with. I don’t use cherry-pick a lot, so it threw me for a loop. Their tagging / release system is something I haven’t dealt with in a few months so I was rusty on that one too. My mental patterns of checking out branches couldn’t be applied to this situation… so my brain immediately declared “shit’s fucked yo” and just stopped reading the messages that were telling me exactly what I needed to do. If the instructions had told me that I needed to merge those tags into my branch, it would have made sense to me, but because I was unfamiliar with their particular git workflow I got stuck. This was the key realization that helped me identify how to solve the problem.
This underscores a key hurdle that all developers have to overcome on their path from beginner to competency. Often when you ask questions in open source communities, responses can be hostile. The question asker is often unaware that the scope of what they are asking far exceeds the topic at hand. If you ask a question about how to do Z, and first I have to explain to you how to do A, B, C, all the way to X and Y before the solution to Z will make sense… I’m effectively doing your homework for you. The key to getting your questions answered is recognizing what you don’t understand, and putting in work to fill in the logical path between those blanks so you can effectively ask the right question, instead of asking others to spend 10x the time explaining the basic concepts that lead up to that topic before we can even cover what was originally asked about.
So the next time you’re trying to do something and some code you found won’t work, take a step back and a few deep breaths. Look at the errors you are seeing and try to think about the larger problem that’s happening. Walk backwards through each step in the sequence till you find the broken link in the chain. Take out a pen and paper and write down the steps of things that are occurring, and take the time to explain the problem to someone else.
The answer might be staring you right in the face, embedded in the blinking red error message you’re just too command-blind understand right now.
Shout outs to the hapipal team, their project is awesome and I’m still figuring out how to deal with the transition from hapi 16 => 17 with their tools and documentation. You should check it out too!
