Tuesday, April 10, 2012

The Notoriously Tricky "Step 0"

I recently posted about "Git for Dummies" and noticed that commented that they had followed my instructions and had a strange permission issue. Wanting to verify everything was correct, I did a quick check and, sure enough I was having the same problem. Upon investigation, I discovered that I had posted a which required a public/private key pair and folks who hadn't already set this up on their machines would get an error. The post was supposed to have been written for a new user and they typically wouldn't have done this. As a long time github user, I did this one time setup ages ago and had totally forgotten about it.

This is common occurrence, so common, that I give it a name... I call it "Step 0". This is a variation of the curse of (prior) knowledge and can be frustrating for both people trying to learn something new as well as people who are trying to explain how to that something to a newbie. In essence, "Step 0" is the prior knowledge necessary and fundamental to performing a task that is so fundamental that it is routinely forgotten until a novice attempts the task for the first time.

As with many things, there is no sure fire solution or way to avoid this, but being aware of the situation can certainly reduce the amount of frustration when it happens. I was about to amend my previous blog post to add the necessary detail, but decided to change the url to the "read only" version. Instead of editing the post to add the 5 steps necessary to set up and use the ssh version, I changed to use the anonymous version that most newbies should start with.

I chose the simpler solution over trying to explain "setting up a github account" and "setting up ssh public/private key pairs" because I think those topics are different and trying to put too much detail can be just a detrimental as not having enough. If someone follows the instructions and they don't work, they can ask a question.

No comments: