improving instructions

pages/overview/getting_started.md

@@ -9,41 +9,48 @@ audience: writer, designer
 
 * Mac computer (recommended). If you have a PC, you need to see [Jekyll on Windows](http://jekyllrb.com/docs/windows/). Make sure you can get Jekyll working on Windows before proceeding.
 * [Ruby](https://www.ruby-lang.org/en/). This should already be installed. Type `which ruby` to confirm. 
-* [Rubygems](https://rubygems.org/pages/download). This is a package manager for Ruby (gems).
-* [Jekyllrb](http://jekyllrb.com/). To install: `gem install jekyll`
+* [Rubygems](https://rubygems.org/pages/download). This is a package manager for Ruby (gems). Type `which gem` to confirm.
+* [Jekyllrb](http://jekyllrb.com/). To install: `gem install jekyll`. Type `which jekyll` to confirm.
 * [Git](http://git-scm.com/download/mac). Type `which git` to see if you already have it installed.
 * Text editor (some examples: Sublime Text, Atom, WebStorm)
 * [iTerm](http://iterm.sourceforge.net/) - optional but recommended instead of Terminal. 
-* [pygments](http://pygments.org/download/) - Pygments handles syntax highlighting. In my experiments, the highlighting seemed better than the default rouge. To install Pygments, you will need Python installed. (If you don't install pygments, you'll get an error when you build the theme.)
+* [pygments](http://pygments.org/download/) - Pygments handles syntax highlighting. In my experiments, the highlighting seemed better than the default rouge highlighter. To install Pygments, you will need Python installed. (If you don't install pygments, you'll get an error when you build the theme.)
 
 {{warning}} These instructions are designed for users on Macs. Jekyllrb supposedly works on Windows but is not officially supported on that platform. See <a href="Jekyll on Windows">http://jekyllrb.com/docs/windows/</a> for more details. {{end}}
 
 ## Build the theme
 
-Because this theme is intended to build multiple outputs from the same project, it doesn't use the default _config.yml file like other Jekyll themes. Instead, each different output has its own config file in the configs directory. 
+{{important}} Because this theme is intended to build multiple outputs from the same project, it doesn't use the default _config.yml file like other Jekyll themes. Instead, each different output has its own config file in the configs directory. As a result, you can't type `jekyll serve` to build the theme, since this command looks for the _config.yml file in your project directory.{{end}}
 
-Each config file has a different preview port and build destination. It also specifies a different audience.
-
-You build the sites by using more specific build commands, like this:
+1. Download the theme from the [documentation-theme-jekyll Github repository](https://github.com/tomjohnson1492/documentation-theme-jekyll). 
+    You can either download it directly by clicking the **Download Zip** button on the right, or use git to clone the repository to your local machine. Note, however, that you won't be using the pull command to update the theme since you'll be customizing it with your own content and won't want to overwrite those customizations.
+2. Note some unique aspects of this theme: *There's a separate config file for each unique output you're building.* Each config file has a different preview port and build destination. It also specifies a different audience.
+    
+    In general, you build the sites by using more specific build commands, like this:
 
+    ```
+jekyll serve --config configs/config_writer.yml --destination ../documentation-theme-jekyll-builds/writer
 ```
-jekyll serve --config configs/config_writer.yml --destination /users/tjohnson/projects/documentation-theme-jekyll-builds/writer
-```
-Because these commands are long and bulky, it's easier to store them in a small shell script and then run the script. In the root directory, you'll find build_writer.sh, which simply contains this build argument. Instead of running the command above, run the following:
+    Because these commands are long and bulky, it's easier to store them in a small shell script and then run the script. 
+3. In the root directory, you'll find build_writer.sh, which simply contains this build argument. Instead of running the command above, run the following:
 
 ```
 . build_writer.sh
 ```
-
-If you run into permissions errors trying to run the .sh file, you may need to change the file permissions to make the sh file executable. To do that, browse to the directory containing build_writer.sh and run the following:
-
-```
+    
+    If you run into permissions errors trying to run the .sh file, you may need to change the file permissions to make the sh file executable. If you find you need to make the file writable (because iTerm won't execute it), browse to the directory containing build_writer.sh and run the following:
+    
+    ```
 chmod +x build_writer.sh
 ```
 
+If the theme builds successfully, great. You can move on to the next section: Customizing the theme. If you run into errors building the basic theme, you must solve them before moving on. See {{troubleshooting}} for more information.
+
 ## Customizing the theme
 
-The theme shows two build outputs: one for designers, and one for writers. Here's how you would customize the theme. In these instructions, I'll assume your project's name is "acme."
+The theme shows two build outputs: one for designers, and one for writers. The dual outputs is an example of the single sourcing nature of the theme. Here's how you would customize the theme. 
+
+{{important}} In these instructions, I'll assume your project's name is "acme."{{end}}
 
 1. Using iTerm, create the directory where you want to install the project. I like using ~[username]/projects, because ~[username] is the default directory that appears when you open iTerm on a Mac. 
     

pages/overview/troubleshooting.md

@@ -3,9 +3,11 @@ title: Troubleshooting
 permalink: /troubleshooting/
 ---
 
-## Address already in use
+## Issues building the site
 
-When you try to build the site, you get this error: 
+### Address already in use
+
+When you try to build the site, you get this error in iTerm: 
 
 ```
 jekyll 2.5.3 | Error:  Address already in use - bind(2)
@@ -20,8 +22,22 @@ Find the PID (for example, it  looks like "22298").
 
 Then type `kill -9 22298` where "22298" is the PID.
 
-## "page 0" cross references in the PDF
+### Pygments not installed
 
- If you see "page 0" cross-references in the PDF, the URL doesn't exist. Check to make sure you actually included this page in the build. If it's not a page but rather a file, you need to add a class to the file so that your print stylesheet excludes the counter from it. Try adding `class="noCrossRef"` as an attribute to the link. In the css/printstyles.css file, there is a style that should remove the counter from anchor elements with this class.
+The config file requires pygments for the highlighter. You must [download and install Pygments]([pygments](http://pygments.org/download/)), which requires Python, in order to use this syntax highlighter. If you don't want to bother with Pygments, open the configuration file and change `pygments` to `rouge`.
+
+## PDF issues
+
+### "page 0" cross references in the PDF
+
+ If you see "page 0" cross-references in the PDF, the URL doesn't exist. Check to make sure you actually included this page in the build. 
+ 
+ If it's not a page but rather a file, you need to add a class to the file so that your print stylesheet excludes the counter from it. Try adding `class="noCrossRef"` as an attribute to the link. In the css/printstyles.css file, there is a style that should remove the counter from anchor elements with this class.
+ 
+ ### The PDF is blank
+ 
+ Check the prince-file-list.txt file in the output to see if it contains links. If not, you have something wrong with the logic in the prince-file-list.txt file. Check the conditions.html file in your _includes to see if the audience specified in your configuration file aligns with the buildAudience in the conditions.html file
+ 
+