Spoiler Alert: You can find the answer here.
We use TFS at work.
Because I believe git could be a great solution for a workflow challenge we’re having on one of the accounts I was just assigned to, I decided to experiment with git-tfs.
Here are the installation instructions from the gittfs github repository:
I understand that many C# developers came from Java, thus had to get VERY familiar with instructions like, “Add the directory that contains git-tfs.exe to your path,” but I feel compelled to mention it is a pretty big road blocker to someone who has never seen or had to do that .
Just a Windows Girl Livin’ in a GUI World
Ok, that was an ode to Jon Skeet’s “Glee” Pecha Kucha Codemash 2012 “Don’t Stop Believing” ending, but if you can relate to that header, I wanted to share a link I found interesting. A Brief History of UNIX is a great Unix 101 for Windows devs, with examples that do a good job of providing reference comparisons.
But back to the point of this post: I came from Mac (way back) to Windows. I am not familiar with UNIX environments. I launch installers to get programs to run from my machine. Yes, I’ve been spoiled, and it’s been quite lovely, but I’m now really trying to embrace this unfamiliar command-line environment territory, and that little assumption that I knew what it meant to add a directory to my path made me lose a day I could have been actually experimenting with git-tfs, instead of trying to understand how to just get git tfs commands not to say “not found.”
Am I trying to bag on the author of Git-tfs?
Not at all – it’s just where I hit a roadblock, so I’m using it as an example.
In their defense, should I have “just known” how to do that?
Maybe. I‘ve just never had to know for anything. That’s all. Now I’m aware.
Have I ever done it before?
If I’ve never done it before, is it possible others might hit the same roadblock?
Maybe, that’s why I’m writing this post.
Did I get pissed when my Google search returned multiple results saying stuff like, “just add it to your path – that’s so trivial” without explanation of HOW do actually do it?
Yes. (Isn’t everything “trivial” once you know how to do it? Sheesh. Any reply that answers with how trivial the answer is, is a friggin’ @sshole response, btw, and an attitude I haven’t seen in the c# world – what’s up with that?)
Am I trying to make the author do crazy, explicit documentation? Not necessarily, although James Yu made some great points in his post on Designing Great API Docs.
In this case, a simple hyperlink to something like How to set the path in Windows 7 (great article with interesting info btw!) could have meant the difference between someone bringing Git to work to use it with their TFS environment & abandoning it altogether (because the one day their schedule allowed for them to actually try to use it was spent banging their head against a wall because of an installation instruction assumption).
The Curse of Knowledge
If you’re not familiar with The Curse of Knowledge, @tomjohnson did a great job summarizing it in a context developers can relate to when he posted, “The more you know an application, the better poised you are to write a good help file. But the more you know an application, the more familiar you are with it, and so you are less likely to write a good help file.”
To all of you wonderful people paving the way for the rest of us – yes you with the UNIX backgrounds that make command-line so intuitive to you, please, please go easy on us =)
Git was initially designed and developed for Linux. By bringing it to Windows, command-line-and-all, with it you are bootstrapping your own Curse of Knowledge.
I suspect I’m not the only one for whom Git is acting as the gateway to cross that command-line & deeper-OS-internals-understanding threshold. Please just take a moment to think about instructions that are atypical for those of us who are used to programs “just working,” post-install.