changed to canonical directories and updated some formatting
added text explaining what is actually going on