Updated readmes

CONTRIBUTING.md

@@ -1,45 +1,81 @@
-How the code in this repo works
-===
+#Overview
+
 Hi! Glad you want to add code to this project. First, a brief overview of what's gone into this repo and some suggestions on how to get started using it.
 
-The frontend stack
----
+Formally, this repository contains a Redux app written with ES6 JavaScript, styled with Sass, and served with hotloading and module support from Webpack. It relies on a backend with a RESTful API, which is a Django server running PostgreSQL in Docker. 
+
+The section "Uh, where does the code even start?" gives a brief overview. The two parts after that detail the frontend and backend stacks, respectively.
+
+#Uh, where does the code even start?
+
+The main body of code for the frontend is in the `app` folder. Upon first loading, `index.js` adds a `Router` component, which uses `routes.js` to decide what React component to render at its child at specific routes/urls. At `http://localhost:3001/app/#/topics/0`, React renders `TopicHighlighter` as the child of the `App` component. 
+
+When `App` from `app.js` was loaded in `index.js`, it called `configureStore` from `appStore.js`, which set up Redux. This call in turn initializes the reducers, which perform the proper (synchronous for now) API calls from `api.js` to the back end so there's data (currently the news articles) to display. 
+
+The backend code is briefly summarized below:
+
+**[overview of how the backend code functions]**.
+
+#The frontend stack
+
 * Redux
 * React
 * ES6
 * Sass
 * Webpack
 
-Formally, this repo contains a Redux app written with ES6 javascript and styled using Sass, served with hotloading and module support from webpack. It relies on a backend with a RESTful API found [here](https://github.com/Goodly/text-thresher-backend) which is a Django server running PostgreSQL in Docker.
+###What's React?
+
+React is like an extension of JavaScript that allows you to write markup HTML inline with logic. Each part of a page should have its own React component, and a React component, once created, can be treated as an HTML tag. For example, once `SomeReactComponent` is created, it can be used as HTML tag `<SomeReactComponent />`.
+
+React allows you to focus on presentational code that determines what to render on the page, and you can treat the presentational code as funnels which accept data and produce the correct visual change.
+
+The React docs aren't so great - more information on React is included in the guide linked to in the **Redux** section. 
+
+###What's Redux?
+
+Redux is a framework exceptionally good for building understandable and manageable UIs, because of its unified state, unidirectional data flow, and pure functional mutations of state. The Redux docs ARE good, and you should read them until at least like the section labeled 'Advanced'. This one is the hardest to understand, after React. Read up and ask questions.
+
+A brief overview of the Redux flow: when using Redux, there is a single state for the entire application. **Reducers** return certain parts of the state. When an event is triggered, a JavaScript object, called an **action**, representing the event, is sent to all the reducers. The reducers then, based on the action's **type**, create a new Redux state (as Redux state is immutable), and a new Redux state is assembled. Now that we have a new, complete state, the React components are re-rendered accordingly.
+
+If you want more information, I wrote a hopefully comprehensive guide on React and Redux [here](https://gist.github.com/JasmineDeng/764dcd7be22288fadfe95bc83f051cd8).
+
+###What's ES6?
+
+ES6 is the next language release of JavaScript. It is made available now by the developer community of Babel, which also transpiles ES6 to ES5 (the current JavaScript release). Essentially, ES6 changed ES5 syntax to become prettier and more readable.
+
+Some major changes in ES6 involve: default values, arrow functions, template literals, the `let` and `const` keywords, etc. A full list of the new features in ES6 can be found [here](http://es6-features.org/).
+
+###What's Sass?
+
+Syntactically Awesome StyleSheets - one of the leading preprocessors of CSS, it is a preprocessor that allows Sass code to be processed into ordinary CSS. You can do this most directly via `sass input.scss output.css`. Sass essentially changes the syntax of CSS to make it easier to use. The current Sass 3.0 is also called "sassy css".
+
+Variables, calculations, mixins, and nesting all help CSS scale way better. A quick guide to Sass can be found [here](http://sass-lang.com/guide).
+
+###What's Webpack?
+
+Webpack is a module bundler. It takes in a bunch of files (HTML, JavaScript, CSS, SCSS, etc.) and turns it into something that can be provided to the client.
+
+The main benefits of Webpack are its powerful hot module reloading (instant updates to React components without refreshing), lazy loading (it only loads what you need), and the efficiency with which it detects, packages, and sends over changes and modules. 
+
+It produces similar results to Grunt and Gulp, but you don't need to write as much code. All the code for Webpack can be found in the `webpack` folder. 
+
+#The backend stack
 
-Uh, where does the code even start?
----
-`index.js` adds a root React component, which contains a `<Router>` which uses `routes.js` to decide what React component to render as its child. On the first load this is probably `App` from `app.js`, but even if it isn't when `app.js` was loaded it called `configureStore` from `appStore.js` which set up Redux. This in turn initializes the reducers, which perform the proper (synchronous for now) API calls from `api.js` to the back end so there's data to display.
+* **[List the backend parts when merged]**
 
-What's React?
----
-The React docs aren't so great - think of it as a extension to Javascript which allows you to write markup inline with logic, and treat view code like funnels which accept data and produce the correct visual change.
+###What's [backend]? **[Place backend information here when merged]**
 
-What's Redux?
----
-Redux is a framework exceptionally good for building understandable and manageable UIs, because of it's unified state, unidirectional data flow, and pure functional mutations of state. The Redux docs ARE good, and you should read them until at least like the section labeled 'Advanced'. This one is the hardest to understand, after React. Read up and ask questions.
+**[misc information]**
 
-I've written a somewhat helpful gist on React and Redux [here](https://gist.github.com/phorust/b4e61af8600f0b2843675f926a9f8ee0).
+#What's ____?
 
-What's ES6?
----
-Pretty dope. It's the next language spec of Javascript, made available now by the lovely developer community making babel, which transpiles ES6 to ES5 (the current js spec). It got renamed to ES2016 but no one uses that name. Basically now, if you have the feeling there's a better way to do what you're doing, there probably is: lambdas, classes, helper functions, better iterators and packing / unpacking.
+I've tried to enumerate all the interesting and useful parts of all the above, so that you can Google the pieces easily. Developer support for this stuff is all great since it's pretty much cutting edge and widely accepted as the way to go. 
 
-What's Sass?
---
-Syntactically Awesome StyleSheets - one of the leading preprocessors of CSS, it compiles? (people use this word way too losely) to plain CSS but makes writing stylesheets not a pain. Variables, calculations, mixins, and nesting (!!) all help CSS scale way better.
+The only thing we're not doing which would be great but not possible (Python has too many benefits for research) is isomorphic Redux, which just means the server also is in JavaScript and runs Redux. 
 
-What's Webpack?
----
-Man this one is hard. In the beginning there was nothing, and then people said wait javascript projects are getting big we should make a build system for javascript. Grunt was born, and compared to previous approaches it was revolutionary - instead of a fat IDE, instead of a build configuration file, you wrote actual code, which would execute and allowed you to be prescriptive rather than descriptive (I think there's two better words to use but I forget) about your build process. Then, people got tired of writing big gruntfiles, so they said hey let's use Gulp and started writing big gulpfiles instead. Gulp has ... better piping and IO redirection, so your tasks can be more powerful? Then, people got tired of the benefits of writing programmatic build files instead of configuration files and went back to writing huge configuration files and started using webpack. The main benefit of webpack is it's extremely powerful hot module reloading and the efficiency with which it detects, packages, and sends over changes and modules. Webpack files are especially gross and hard to understand but... these benefits are worth it.
+#Additional information
 
-If you can't tell I still personally use grunt or gulp and I'm tired of spending more time writing effecient and cutting edge boilerplate than writing applications.
+###React Routing 
 
-What's ____?
----
-I've tried to enumerate all the interesting and useful parts of all the above, so that you can Google the pieces easily. Developer support for this stuff is all great since it's pretty much cutting edge and widely accepted as the way to go. The only thing we're not doing which would be great but not possible (Python has too many benefits for research) is isomorphic Redux, which just means the server also is in javascript and runs redux.
+The part of the url after the `#` becomes the route fed into `routes.js`. The route for each `Route` tag is decided by the `path` property. The default url `http://localhost:3001/app/#/topics/0` means that the `App` and `TopicHighlighter` component are both rendered, with `TopicHighlighter` as the child component of `App` and the `0` in the url the `:articleId` parameter for that `Route`. Thus, `/` only renders `App`, while going to `/topics/0` then renders `TopicHighlighter` as the child of the `App` component. The same idea can be applied to the `Quiz` component at the path `/quiz`.

README.md

@@ -1,24 +1,62 @@
-# annotator-content-analysis
-An annotation interface for detailed text annotation by crowdworkers along researcher-defined topics of interest.
+# TextThresher
 
-Built with (react)[https://facebook.github.io/react/] and (redux)[https://github.com/reactjs/redux].
+An annotation interface for detailed text annotation by crowdworkers along researcher-defined topics of interest. Under development for the
+[Deciding Force Project](http://www.decidingforce.org/). Currently, this app only runs locally.
 
-####To setup
+Built with [React](https://facebook.github.io/react/) and [Redux](https://github.com/reactjs/redux).
 
-From the project directory, run
+# To setup
 
+The backend is supported by Docker. If you do not have it already, you will need to install it.
+* For OS X, go [here](https://docs.docker.com/docker-for-mac/).
+* For Windows, go [here](https://docs.docker.com/docker-for-windows/).
+* For Ubuntu and other Linux distributions, go [here](https://docs.docker.com/engine/installation/linux/ubuntulinux/).
+
+Once installed, start the Docker application (if on a Mac), then go to the project directory and run:
+
+1. `docker-compose up`
+2. `./init_docker.sh`
+3. `npm install`
+4. `bower install`
+
+You will only need to run the above commands once. Those will do the preliminary setup for the application by installing the dependencies and seeding the Docker containers to setup the database.
+
+You might also want to install Devtools for [React](https://facebook.github.io/react/blog/2015/09/02/new-react-developer-tools.html). For Redux, you can install the [Google Chrome extension](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd) or use the other methods described in the README [here](https://github.com/zalmoxisus/redux-devtools-extension).
+
+**Note:** If you are setting up Docker a second time, you may want to first remove the previous database containers with `docker-compose rm db`.
+
+**Note:** If you are on Ubuntu and encounter the error:
 ```
-npm install
-bower install
+Couldn't connect to Docker daemon at http+unix://var/run/docker.sock - is it running?
 ```
+run `sudo groupadd docker` and `sudo usermod -aG docker $USER`. This is also listed as a first step [here](https://docs.docker.com/engine/installation/linux/ubuntulinux/#/create-a-docker-group) under "Optional Configs".
+
+# To develop
+
+In the project directory, run `docker-compose start` and `npm run dev`.
+
+To view a browsable interface for the queries, navigate to `localhost:5000/api`. Another browsable interface is available [on Heroku](http://text-thresher.herokuapp.com/api/), but is not fully up-to-date.
+
+**Note:** If you encounter an error that the module `text-highlighter/src/TextHighlighter` cannot be found, you will need to update brew by running `brew update`. 
+
+# To deploy
+
+In the project dictory, run `docker-compose start` and `npm run deploy`. The output files will be written to the `dist` folder.
+
+**NOTE:** this command currently currently not fully functional and needs to be upgraded. Running `npm run dev` instead will show the most recent version of the code.
+
+To deploy the backend to Heroku:
 
+- push the code to Heroku `git push heroku`
 
-You might also want to install Devtools for (React)[https://facebook.github.io/react/blog/2015/09/02/new-react-developer-tools.html] and (Redux)[https://github.com/zalmoxisus/redux-devtools-extension].
+- Reset the db with `heroku pg:reset postgres --confirm text-thresher`
 
-####To develop
+- Prepare the database. You have two options.
 
-Run `npm run dev` from the project dir to build and serve the development app.
+   - To initialize the database but not load data, run `heroku run python manage.py syncdb`
 
-####To deploy
+   - To initialize the database with a copy of your local data, verify that your
+local postgres database has data and works when you run the app locally,
+then run `heroku pg:push LOCAL_DB_NAME postgres`
 
-Run `npm run deploy` and the output files will be written to the `dist` fodler.
+- Visit the [application](http://text-thresher.herokuapp.com/api/) to make sure it worked.