minor tweaks to current documentation based on setup work (#26)

* minor tweaks to current documentation based on setup work

* include note on environment configuration for sculpin

* Edited sentences for flow; tweaked whitespace and formatting.

* update documentation around changing and customizing

* Remove redundant section.

* Specify scripts using Butler's own gulp, and allow running butler directly.

README.md

@@ -1,57 +1,73 @@
 # Butler
-The beginnings of a Sculpin-based style guide creation tool. 
+
+A tool to automate front-end development tasks and streamline prototyping.
 
 ## Dependencies
-1. NodeJS 
-   1. To intall NodeJS using Homebrew run `brew install node` 
-1. [Sculpin](https://sculpin.io/getstarted/)
-    1. `curl -O https://download.sculpin.io/sculpin.phar`
-    2. `chmod +x sculpin.phar`
-    3. `mv sculpin.phar sculpin` or if you are using vagrant run `sudo -H mv sculpin.phar /bin/sculpin` and skip step 4
-    4. `mv sculpin ~/bin/` 
+
+* **NodeJS**
+  1. If you are running Butler on your local machine, you can install using Homebrew: `brew install node`
+  1. If you are running Butler on a Vagrant, our default VM comes with node installed.
+* **Sculpin**
+  1. Butler expects Sculpin to be included in your project using `composer`. Make sure you've run `composer install` in your project before running Butler.
+  1. If you would like to use globally-installed Sculpin instead: first, follow [Sculpin's installation guide](https://sculpin.io/getstarted/); then configure Butler to use it by setting `defaults.sculpin_run = 'sculpin';` in your project's `conf/butler.defaults.js` file.
 
 ## Add Butler to a project
-1.   If the project does not already have npm dependencies run `npm init` to create a `package.json` file
 
-1.   Add Butler as a dependency by running `npm install --save palantirnet/butler`
+1. If the project does not already have npm dependencies, run `npm init` to create a `package.json` file
+1. Add Butler as a dependency: `npm install --save palantirnet/butler`
+
+  When Butler is first installed, it will ask for the location of your project's GitHub repository. Please provide the HTTPS link for the project repository, e.g. `https://github.com/palantirnet/[project].git`; Butler will use this information to deploy the styleguide.
 
-1.  Duplicate `STYLEGUIDE_TEMPLATE`, rename it `styleguide`, and add it to the project's root directory
+  Butler will store this information in a project-specific configuration file at `conf/butler.defaults.js`.
 
-1.  Add the following code to your project's `package.json`
+1. Copy the `STYLEGUIDE_TEMPLATE` to your project's root directory and rename it `styleguide`. This name is required.
+1. Add the following code to your project's `package.json`:
 
-````
-"scripts": {
-	"butler": "gulp --gulpfile node_modules/butler/gulpfile.js develop",
-	"linting": "gulp --gulpfile node_modules/butler/gulpfile.js test",
-	"deploy": "gulp --gulpfile node_modules/butler/gulpfile.js deploy"
-},
-````
+  ````
+  "scripts": {
+    "butler": "node_modules/butler/node_modules/.bin/gulp --gulpfile node_modules/butler/Gulpfile.js",
+    "develop": "node_modules/butler/node_modules/.bin/gulp --gulpfile node_modules/butler/Gulpfile.js develop",
+    "linting": "node_modules/butler/node_modules/.bin/gulp --gulpfile node_modules/butler/Gulpfile.js test",
+    "deploy": "node_modules/butler/node_modules/.bin/gulp --gulpfile node_modules/butler/Gulpfile.js deploy"
+  },
+  ````
+1. Add the `node_modules` directory to your project's .gitignore
+1. Commit Butler's changes to your project:
+  * `.gitignore`
+  * `conf/butler.defaults.js`
+  * `package.json`
+  * `styleguide/`
+1. When you're ready to start working on code, run `npm run butler`
+1. The styleguide can be found on port 8000:
+  * `http://[project].local:8000` if you're running Butler on a Vagrant
+  * [http://localhost:8000](http://localhost:8000) if you're developing locally
 
-1.  Run `npm run butler` and begin developing normally
+## What does this Butler do?
 
-1.  Navigate to `localhost:8000` or `[project].local:8000` in your browser to see the styleguide
+* `npm run butler`
 
-1.  Add `node_modules` to your project's `.gitignore` file and commit your project's new `package.json`
+  This is the default task. This will watch your sass/sculpin files for changes and compile/build accordingly. It will also flag any sass linting errors before compiling. It will output CSS that has been been minified and optimized.
 
-## What does this Butler do
-*  `npm run butler` 
-
-    This is the default task. This will watch your sass/sculpin files for changes and compile/build accordingly. It will also flag any sass linting errors before compiling. It will output CSS that has been been minified and optimized. 
+* `npm run butler -- sass`
 
-*  `npm run linting`
+  Just compile the sass. You can also use this syntax to run any task from the Gulpfile.
 
-    This is the testing task it will run linters as their own tasks. To learn more about configuring and customizing the linters for Butler check the [linters documentation](/docs/LINTERS.md).
+* `npm run linting`
 
-*   `npm run deploy`
+  This is the testing task it will run linters as their own tasks. To learn more about configuring and customizing the linters for Butler check the [linters documentation](/docs/LINTERS.md).
 
-    This is a task to deploy the static styleguide to GitHub pages. It will deploy to `gh-pages` branch of the repo defined in the `config/paths.js`. Each commit for this process will default to the message: "Updated with Butler - [timestamp]". *Note: When you are deploying, Butler will ask you for your github credentials multiple times. Enter your own github credentials as prompted.*
+* `npm run deploy`
 
-## Making Changes to Butler
-Please feel free to change/extend/break this Gulpfile to fit the specific needs of the project.
+  This is a task to deploy the static styleguide to GitHub pages.
 
-For more information on contributing to this project check the [contributing documentation](/docs/CONTRIBUTING.md).
+  Butler will build a Sculpin production artifact to `styleguide/output_prod` and deploy the production artifact to `gh-pages` branch of the repo defined in the `conf/butler.defaults.js`. Each commit for this process will default to the message: "Updated with Butler - [timestamp]".
+
+  You may want to create a `sculpin_site_prod.yml` to define the site URL once deployed. You can find out more information about environment aware configuration for Sculpin [here](https://sculpin.io/documentation/configuration/).
+
+  *Note: When you are deploying, Butler will ask you for your GitHub credentials at least once, possibly multiple times. Enter your own GitHub credentials as prompted.*
 
 ## Troubleshooting
+
 For immediate concerns, if you have comments/questions/concerns about working with this please talk to Lauren.
 
 To file bug or feature requests, please use the GitHub issue queue for this repository. You can see more about our Issue Guidelines in the [contributing documentation](/docs/CONTRIBUTING.md).

config/butler.defaults.js

@@ -30,7 +30,8 @@ defaults.stylelint = { configFile: 'config/linters/stylelint.config.json' };
 // Deploy defaults
 // point to the correct repo & include deploy message
 defaults.deploy = {
-  remoteUrl: defaults.repo
+  remoteUrl: defaults.repo,
+  message: 'Updated with Butler - [timestamp]'
 };
 
 module.exports = defaults;

docs/CONTRIBUTING.md

@@ -14,9 +14,9 @@ As a major part of the Palantir Tool Chain, this repository should be continuall
 
 1. Modifications to the default tool chain should be reviewed during Sprint Retrospectives.
 1. If those modifications are found valuable to the Palantir tool chain as a whole, they should be brought up as a topic at bi-weekly DEFEND meetings.
-1. Such meetings will be used as an open forum for debate and/or voting on the issue.
+1. Such meetings will be used as an open forum for debate and/or vote on the issue.
 1. Should the issue be approved by DEFEND, one would create an PR against this repository (following the above stated standards) to incorporate the work into the base toolchain.
-1. PRs are eligible to be merged once when there is consensus and approval from a Senior Designer and Senior Front End Developer in the case of changes to HTML/CSS/JS, and in the case of changes to Butler, it requires approval from Lauren and Ryan.
+1. PRs are eligible to be merged once when there is consensus and approval from a Senior Designer and Senior Front-End Developer.
 
 Issue, PR and Commit Guidelines below generally followed those outlined in the [documentation repo](https://github.com/palantirnet/development_documentation/blob/master/CONTRIBUTING.md)
 

docs/LINTERS.md

@@ -2,7 +2,7 @@
 This document goes over the linting functionality included in Butler and how it can be ignored or extended for project use.
 
 ## Stylelint
-Butler runs stylelint as a PostCSS command that ensures that we are writing quality styles. 
+Butler runs stylelint as a PostCSS command that ensures that we are writing quality styles. Butler will automatically lint as it compiles. As a designer or developer, you will see warnings and errors in the Terminal as they are found by Butler.
 
 Default style lint configuration can be found at `butler/config/linters/stylelint.config.json`. It is based on a few defaults that we should be matching in our CSS. 
 
@@ -23,4 +23,6 @@ Butler incorporates the [stylelint-selector-bem-pattern plugin](https://github.c
 .MyComponent-other {}
 ````
 
+There is an example class in Butler's `styles.scss`. It is there for example only, to show what _NOT_ to do for class names and what comments _to do_ if you want the linter to check class names. 
+
 You can read more documentation on how the selector linter works and how to customize it [here](https://github.com/postcss/postcss-bem-linter).