Programming is hard. Especially when you are just getting started, there are a lot of things, in Donald Rumsfeld's words, that you "don't know that you don't know." Lots of quickstarts for beginners assume the reader knows things about how the command line works that my experience shows they don't. I do lots of user tests with people new-to-programming and see these errors again and again.

I thought I'd put together a short list of things quickstart writers leave out, that will still leave you totally stumped.

• Most of the time if you see an indented block of text in a fixed width font, like this:

  $ foo baz bang
  

  It usually means you're supposed to do something with the text in the box.

• If the text in the box has a dollar sign at the beginning of it, it represents a command you are supposed to enter in your Terminal. If you get an error that looks like this:

      bash: $: command not found
  

  It means you aren't supposed to copy the dollar sign. Just type foo baz bang and hit <Enter>. Unfortunately it's hard to Google for dollar signs, so you can't really figure out what you did wrong.

• If there's a dollar sign, followed by some more text on the lines below the dollar sign, the lines below represent the output of running the command correctly. For example:

      $ python run.py
       * Running on http://127.0.0.1:5000/
       * Restarting with reloader
  

  You are only supposed to type in python run.py into your Terminal. The rest of that stuff is the output of running the command correctly.

• If the block of text doesn't have a dollar sign, it's probably a snippet of code you are supposed to copy into a text editor and save into a file (On Mac, use TextWrangler; on Windows use Notepad++). Hunt around the quickstart for a filename you should use.

• If they don't tell you where to save the files, create a new folder and save all of the files in there, in the top level.

• If the command line mentions a file you've recently created, like this:

      $ python run.py
  

  You need to run the command from "inside" the same folder as the file. The terminal has a notion of being "in" a directory (Directories and folders are the same thing). Here's a short guide:

  • To figure out which directory you are in, type pwd and press Enter. (pwd stands for "print working directory").

  • To list all files and folders in the current directory, type ls -al and press Enter.

  • To go into a folder below the current one, type cd Documents (or whichever folder you are trying to navigate to). To do more than one type cd Documents/code.

  • To go up a level type cd ..

  Once you're "in" the right place you should be able to run the command properly.

• If you feel like you are spinning your wheels, ask for help! It's important to know how to ask. Make sure to tell people a) what you are trying to do, b) what you expected to happen, and c) what actually happened. Bonus points if you can talk about things you tried previously and why they failed to do what you wanted.

As an author of a quickstart myself, I feel like I owe an apology to users who are just getting started, for not including this information along with our guide. Sadly the terminal is just about the least beginner-friendly piece of software I can think of, and when you are just getting started, so-called "simple" errors can totally derail you and make you want to go outside and play Frisbee or roller blade.

Hopefully these tips will help you get started doing that cool tutorial you've always wanted to do.

Liked what you read? I am available for hire.