Update docs and contributing guide

Author: ehzhang

.docs/images/screenshots/admin-metrics.png

@@ -0,0 +1,31 @@
+Contributing to HELPq
+=====================
+
+Thank you for using HELPq, and we're really excited that you want to help out!
+
+Development Process
+-------------------
+
+This project is developed mostly by me (Edwin Zhang), but quite a few hackathons have their own forks. Releases to master can be expected to be stable and ready to use (with configuration, of course), but dev will be the most up to date.
+
+Pull Requests
+-------------
+
+We actively welcome your pull requests!
+
+However, before you begin, please create an issue so we can determine if the work, feature, or bugfix either has someone is already working on it as a part of the current roadmap, or if the feature is not something that would belong in the HELPq as a core feature.
+
+This is mostly meant for discussion, so we can discuss things fully and make a really awesome product :)
+
+Issues
+------
+
+We use issues to track public bugs. Please make sure your description is clear and has sufficient instructions to be able to reproduce the issue.
+
+We also use issues to track feature requests and discuss. Please mark your issue as 'Feature Request' in this case!
+
+
+Coding Style
+------------
+
+Keep it clean, and keep things modular!

.docs/images/screenshots/admin-users.png

@@ -1,37 +1,219 @@
 HELPq
+======
 
 An extensible, customizable real-time queue system, built with [Meteor](https://www.meteor.com/).
 
-** This is beta release. This queue is fully functional, but code will move around and features will be added over the next few months. Keep checking back for the most up to date. **
+![Home Screen](./.docs/images/screenshots/home.png)
+
+[Go directly to setup information](#bring-helpq-to-your-hackathonclassroom)
+
+What is this?
+------------
+
+HELPq was originally built for [HackMIT](https://hackmit.org), but has been used at hackathons like [Blueprint](http://blueprint.hackmit.org), [Meteor Summer Hackathon 2015](http://meteorhack.meteor.com/), [WHACK](http://wellesleyhacks.org/), [MakeMIT](http://makemit.org/) and [WildHacks](http://wildhacks.org/) (among others!).
+
+It is a real-time help queue and mentor management application, targeted at hackathons and classrooms, where there is a need for issues to be claimed and satisfied within minutes. It includes a simple interface for requesting tickets, claiming tickets, administrating users/mentors, and examining metrics.
+
+It is built with an emphasis on three fundamental user experiences:
+
+### Keep it simple
+
+Students should be able to log in and do exactly what they want - submit a ticket. Nothing more complicated than that.
+
+### Pull, don't Push
+
+Mentors should not receive any type of push notifications when tickets are requested. Instead, mentors should be pulling from the mentor view and claiming tickets whenever they see them. That way, mentors will not get annoyed by a feed of requests and instead provide high-quality advice because they are themselves actively seeking out people to help.
+
+### In-person interaction
+
+Mentors can claim tickets, complete tickets, or choose to reopen them. Mentors can only claim a single ticket at any given time. There is no ability to message a student through the app in order to encourage a mentor to find that student and help them in person. A student can, however, choose to include other contact information in case contact is needed to clarify location.
+
+
+Features
+---------
+
+### Home
+
+![Home Screen Labeled](./.docs/images/screenshots/home-labeled.png)
+
+#### 1 - Ticket Request
+
+Users can request a ticket, by providing their problem description, where they are, and how they can best be contacted. This copy can be easily modified in one of the config files!
+
+Once submitted, users have an option to cancel their ticket ("Nevermind!"). Tickets will also expire based on a value determined by the admin.
+
+#### 2 - Announcements
+
+Admin can send out announcements with varying colors through the admin dashboard, which appear on on the home screen.
+
+#### 3 - Mentor Status
+
+The mentor status bar shows how many mentors are currently online, and calculates the expected wait time based on historical ticket claim and completion times.
+
+#### 4 - Current Queue
+
+The current queue shows who is currently in the queue and which people are currently receiving help. Because the nature of questions available mentors can address are highly variable, tickets will often not be answered in order of submission.
+
+### Mentor
+
+![Mentor Screen Labeled](./.docs/images/screenshots/mentor-labeled2.png)
+
+If a user is a mentor, they will have an inbox icon in the top right they can click to navigate to the mentor view. If the HELPq is being viewed on mobile or a very narrow window, the app is responsive and will pull up a navigation bar on the bottom for Home, Mentor, and Profile.
+
+Mentors should be mobile, and the HELPq is designed for mentors to browse the help tickets on their smart phones.
+
+#### Claim
+
+You can claim a ticket by selecting "Claim Ticket". This will notify the user that you are on your way! Once a ticket is claimed, you cannot claim another ticket unless you complete or reopen the ticket.
+
+#### Complete
+
+Once you are done working with a student, you should mark that ticket as completed. This will give the student an opportunity to rate their experience with you!
+
+#### Reopen
+
+You can choose to reopen the ticket if you feel like you could not adequately solve the problem, or think someone would be better at addressing it.
+
+### Admin
+
+![Admin Users](./.docs/images/screenshots/admin-metrics.png)
+
+The admin dashboard has a lot of useful features for hackathon organizers or class staff! Shown above is the Metrics dashboard.
+
+#### Announce
+
+The announcement section allows you to create announcements for the home screen, with a variety of different colors.
+
+#### Users
+
+The users table lets you see all of the current users, and mark them as mentor or admins. You can also edit other user's information - of course, be responsible with this power!
+
+#### User Creation
+
+Login is done through Github or Facebook (which can be enabled or disabled in a config file), but you can manually create user accounts.
+
+This takes a CSV formatted string, which will then check your format, and create users asynchronously. If a user's account creation fails, the result will be shown.
+
+This feature was designed for use in classroom settings, or other restricted access settings, so that you can create an account for each student and a password unique to them.
+
+This feature is also useful for when a user does not want to login with Facebook or GitHub (even though only public information is retrieved).
+
+#### Tickets
+
+The tickets table will show you a history of all tickets.
+
+- Green: tickets have been completed
+- Red: tickets that have been cancelled
+- Yellow: tickets that have expired
+- Grey: tickets that are currently claimed
+
+#### Metrics
+
+The metrics pane shows a lot of information regarding the usage of the queue.
+
+The first is a metrics summary, which includes average, median, and std dev of response time and completion time, as well as the raw average of all ticket ratings.
+
+The leaderboard also shows the top 10 mentors with ratings. Their rating is not a raw average of their tickets, but instead blurred slightly with weighting. This is to avoid the situation where a user with a single 5 star rating would be listed above another user with four 5 star ratings and a single 4 star rating.
+
+#### Feedback
+
+The feedback section is a feed of all mentor feedback, with star rating and a note. Bad ratings are highlighted.
+
+#### Settings
+
+Settings allows you to adjust various settings in the queue. Right now, you can open/close the queue and set the time for when tickets expire.
+
+
+Usage Data
+----------
+
+We've used this at a bunch of hackathons and we have some data on them :)
+
+| Hackathon | Date | Response Time (avg, median, std dev) | Completion Time (avg, median, std dev) | Rating Avg | Total Users | Total Mentors | Total Tickets|
+|-----------|------|--------------------------------------|----------------------------------------|------------|-------------|---------------|--------------|
+|**Blueprint High School Hackathon 2015** | 2/22/2015 | 5 min 11 sec, 1 min 26 sec, 9 min 54 sec | 10 min 37 sec, 6 min 29 sec, 13 min 23 sec | 4.9 | 193 | 64 | 170 |
+|**Meteor Summer Hackathon 2015** | 8/8/2015 | 6 min 21 sec, 2 min 29 sec, 10 min 58 sec | 5 min 46 sec, 1 min 26 sec, 12 min 3 sec | 4.9 | 68 | 66| 37 |
+|**HackMIT 2015** | 9/19/2015 | 9 min 37 sec, 2 min 48 sec, 28 min | 16 min 30 sec, 10 min 1 sec, 22 min 59 sec | 4.7 | 425 | 242 | 502 |
+|**WHACK 2015** | 10/3/2015 | 7 min 55 sec, 4 min 56 sec, 12 min 30 sec | 18 min 19 sec, 13 min 2 sec, 17 min 27 sec | 4.9 | 87 | 39 | 94 |
+
+
+Bring HELPq to your hackathon/classroom!
+========================================
 
 Requirements
 ------------
 
+Make sure that you hate `meteor` installed.
+You can install Meteor through their [website.](https://www.meteor.com/)
+
+
 Quickstart
 ----------
+
+#### Mac OS X, Linux
+
 ```sh
   ./create_config
   meteor
 ```
 
+#### Windows:
+
+Copy the `private/config.json.template` into `private/config.json`
+
+```sh
+  meteor
+```
+
+Deploy
+------
+**IMPORTANT**
+
+Without login configuration, you will only be able to login with the admin username and password specified in `private/config.json`.
+
+To change the password of the admin account after deployed, you must manually remove the admin user through the meteor mongo shell, and then redeploy with a new admin username/password value. *This will be changed pretty soon*
+
+Deploy with:
+
+```sh
+  meteor deploy <your domain name>.meteor.com
+```
+
 Configuration
 -------------
-For front end branding, edit `client/stylesheets/scss/_branding.scss`
 
-To edit text, edit `lib/constants.js`
+#### Login
 
 To configure login, edit `private/config.json`
 
 In `private/config.json`, provide the appropriate application id/secret combinations
 for either facebook or github authentication, or choose to disable them.
 
-This will also contain the admin account username and password you'll use for the initial login.
+#### Branding
 
-Deploy
-------
+For front end branding, edit `client/stylesheets/scss/_branding.scss`
+
+In this file, you will find brand variables and classes for the main splash and main banner.
+
+You can edit these and observe the changes. There are also comments to explain what each setion does.
+
+#### Copy
 
-Deploy with `meteor deploy <your domain name>.meteor.com`
+To edit copy, edit `lib/constants.js`.
 
-Login as an Admin to grant yourself mentor/admin access using the username/password specified in
-your `config.json` file.
+In this file, you will find a place where you can change various strings across the site, including the title of your app.
+
+Orientation
+-----------
+
+The queue has been found to be most effective with an orientation with mentors and a tight integration with the way a hackathon/classroom manages mentorship. If you'd like to talk about how this could work for your hackathon/classroom, don't hesitate to email me at [[email protected]](mailto:[email protected])!
+
+Feedback
+--------
+
+Have you used HELPq or are planning to use it at your hackathon? I'd love to hear how effective it was, what kinds of metrics you got, and what kinds of things people wanted. Don't hesitate to email me at [[email protected]](mailto:[email protected])!
+
+Contributing
+------------
 
+I'd love to take pull requests! Please read the [Contributing Guide](CONTRIBUTING.md) first!

.docs/images/screenshots/home-labeled.png

@@ -7,10 +7,10 @@
 // danger: generally some sort of red to indicate danger
 //------------------------------
 
-// Primary color of your brand
+// Primary color of your brand (Used for primary buttons, glows, etc.)
 $brand-primary: #137DC3;
 
-// Secondary color of your brand
+// Secondary color of your brand (used for secondary buttons)
 $brand-secondary: #FFBF0A;
 
 // Success Buttons
@@ -40,6 +40,9 @@ $github-gray: #e4e4e4;
 // Change the default fonts.
 // font-stack: base fonts
 // logo-font: font for the logo
+//
+// To use fonts other than Lato/Montserrat, edit client/app.html to include
+// the appropriate fonts.
 //------------------------------
 
 // Styling for the fonts
@@ -61,24 +64,41 @@ $github-gray: #e4e4e4;
 // Set branding here by changing up the color of text and the background images
 // or background color.
 //------------------------------
+
+// The splash is the login page.
 #splash {
+
+  // There are a few defaults that are here, which you can comment/uncomment,
+  // but you should feel free to change this to whatever you want.
+
+  // Font color
   color: white;
-  background: $brand-primary;
 
-  // Comment these two lines if you want a single image to cover the entire page.
-  //  background: url(/assets/images/background.jpg) no-repeat center center;
-  //  background-size: cover;
-//  background: $brand-primary;
+  // Basic white text on brand color:
+  // background: $brand-primary;
+
+  // Single background image covering the entire page
+  // background: url(/assets/images/background.jpg) no-repeat center center;
+  // background-size: cover;
+
+  // Background image that repeats
   background: url(/assets/images/geometry2.png) repeat;
 }
 
 
 // Banner which appears under the nav, and on each page.
 #banner {
+  // Font color
   color: white;
-  //  background: url(/assets/images/background.jpg) no-repeat center center;
-  //  background-size: cover;
-  //  background: $brand-primary;
+
+  // Single background image covering
+  // background: url(/assets/images/background.jpg) no-repeat center center;
+  // background-size: cover;
+
+  // Basic white on brand color:
+  // background: $brand-primary;
+
+  // Repeated Background:
   background: url(/assets/images/geometry2.png) repeat;
 }
 

.docs/images/screenshots/home.png

@@ -4,12 +4,12 @@
     "password": "hunter2"
   },
   "github": {
-    "enable": true,
+    "enable": false,
     "clientId": "github-client-id",
     "secret": "github-secret"
   },
   "facebook": {
-    "enable": true,
+    "enable": false,
     "appId": "facebook-client-id",
     "secret": "facebook-secret"
   },