Reorganized README and tighten YARD config

[Fixes #110]

.gitignore

@@ -12,19 +12,11 @@ capybara-*.html
 rerun.txt
 pickle-email-*.html
 /public/assets/
+.yardoc
 
 ## Environment normalisation:
 /.bundle
 /vendor/bundle
 
-# these should all be checked in to normalise the environment:
-# Gemfile.lock, .ruby-version, .ruby-gemset
-
-# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
-.rvmrc
-
 #dotenv
 .env
-
-#vagrant
-.vagrant

.yardopts

@@ -1 +1 @@
--o docs - CONTRIBUTING.md LICENSE.txt
+--title Coyote -c -o docs --files CONTRIBUTING.md,LICENSE.txt

README.md

@@ -1,94 +1,97 @@
-Coyote
-====
+# Coyote
 
 [![Travis CI](https://travis-ci.org/coyote-team/coyote.svg?branch=master)](https://travis-ci.org/coyote-team/coyote)
 [![Code Climate](https://codeclimate.com/github/coyote-team/coyote/badges/gpa.svg)](https://codeclimate.com/github/coyote-team/coyote)
 [![Test Coverage](https://codeclimate.com/github/coyote-team/coyote/badges/coverage.svg)](https://codeclimate.com/github/coyote-team/coyote/coverage)
 
-An open source image annotation app and API to enable the distributed annotation of museum images. Coyote is built on [Ruby-on-Rails](http://rubyonrails.org/) with MySQL (via MariaDB).  
+An open source image annotation app enabling the distributed annotation and comprehensive representation of images. Long descriptions can range from one sentence to several paragraphs. The software was developed by the [Museum of Contemporary Art Chicago](https://mcachicago.org/) to support a distributed workflow for describing their images and publishing those descriptions to the web. 
 
-The software was developed by the [Museum of Contemporary Art Chicago](https://mcachicago.org/) to support a distributed workflow for describing their images and publishing those descriptions to the web. 
-See [coyote.pics](https://coyote.pics/) for an example annotation.
+## Example
 
-Coyote offers role-based logins to facilitate image description tasks. Administrators approve, assign, and review descriptions. Cataloguers create descriptions from an assignment queue or select images to describe. 
-To provide additional context for cataloguers, Coyote presents the image caption, where available. Coyote allows multiple cataloguers to describe an image; it also allows a single cataloguer to create multiple description– potentially in multiple languages –of the same image.
+An image like this would traditionally be described by [alt text](https://en.wikipedia.org/wiki/Alt_attribute) like <q>A red, white, and blue fabric canopy presses against walls of room; portable fans blow air into the room through a doorway.</q>: 
 
-More information about image description projects at the MCA and elsewhere is available at [coyote.pics](http://coyote.pics), along with contact information for the project team. You can also view or hear image descriptions on the [MCA website](http://mcachicago.org).
+![MCAChicago sample image T.Y.F.F.S.H](doc_assets/mca_sample.png "A red, white, and blue fabric canopy presses against walls of room; portable fans blow air into the room through a doorway.")
 
-## Developer Setup
+*Kris Martin, Belgian, b. 1972. T.Y.F.F.S.H., 2011. Collection: Museum of Contemporary Art. Photo: Nathan Keay, © MCA Chicago.*
 
-```bash
-# installs gems, walks you through setting .env variables, creates databases, and adds seed data
-bin/setup
-bin/rails server && open http://localhost:3000
-```
-
-The [seed script](https://github.com/coyote-team/coyote/blob/master/db/seeds.rb) builds a simple user, so you can login as `user@example.com`.
+Coyote aims to provide more comprehensive representations:
 
-## Documentation
+> This is an installation that viewers are invited to walk inside of. From this viewpoint you are looking through a doorway at a slight distance, as if standing inside of a large cave and looking out of its narrow entrance at the world outside. 
+> The walls of this cave are alternating stripes of red, white, and blue material that seems to be made of some kind of thin fabric. These colored stripes spiral around toward the entrance, as if being sucked out of the opening. 
+> The inside of the cave is more shadowed and the area outside is brightly lit. Gradually you notice that there are in fact two openings lined up in front of each other, straight ahead of you: the first one is a tall rectangle—the red, white and blue 
+> fabric is wrapped through the edges of a standard doorway; beyond that it continues to spiral around toward another circular opening. The center of this circle is much brighter, as if one had finally escape from the cave. 
+> At the center of that circular opening you see two large white fans facing your direction, blowing air into the cave-like opening. Beyond the fans you see a brown, square form, which is the bottom of a huge wicker basket. 
+> This basket, lying on its side, helps to reveal the truth about what you are seeing: You are standing inside of a huge hot air balloon, which is lying on its side. Blown by the fans, the fabric billows out to press out against the existing w
+> alls of a large room, the malleable shape of the balloon conforming to the rectangular surfaces of an existing building–the gallery that contains it.
 
-Our YARD documentation is hosted at [coyote-team.github.io][https://coyote-team.github.io/coyote/].
+More information about image description projects at the MCA and elsewhere is available at [coyote.pics](http://coyote.pics), along with contact information for the project team. You can also view or hear image descriptions on the [MCA website](http://mcachicago.org).
 
-## Usage 
+## Table of contents
 
-```bash
-# Run the server
-bin/rails s
+- [Developer Setup](#developer-setup)
+- [Documentation](#documentation)
+- [Heroku Deployment](#heroku-deployment)
+- [API](#api)
+- [Strategies](#strategies)
+- [Data Model](#data-model)
+- [Links](#links)
+- [Contributors](#contributors)
+- [License](#license)
 
-# Automatically run tests as you work. You might need to install a shim for guard.
-guard
+## <a name="developer-setup"></a>Developer Setup 
 
-# Run the tests on their own
-bin/rspec
+_Beginning Developers_
 
-# Run the console
-bin/rails c
-```
+The app can run in a self-contained Docker container, which you can use for development. For more details see [local development with Docker Compose](https://devcenter.heroku.com/articles/local-development-with-docker-compose).
 
-## Test
+1) Install [Docker Community Edition](https://www.docker.com/get-docker)
 
-Lint the model factories ([more info](https://github.com/thoughtbot/factory_girl)):
+2) Run the following commands:
 
 ```bash
-bin/rake factory_girl:lint
-
+git clone https://github.com/coyote-team/coyote.git
+cd coyote
+docker-compose build # downloads images, builds containers
+docker-compose up    # start running containers
+docker-compose exec web bin/rake db:setup db:migrate db:seed                    # prepare database, add seed data
+docker-compose exec web bin/rake coyote:admin:create[user@example.com,password] # create initial user
 ```
 
-Then, run the test suite:
+3) Open `http://localhost:3000` in your browser.
+
+Once the app is running you can interact with it using commands like this:
 
 ```bash
-# Once
-bin/rspec
+docker ps                                 # list running containers
+docker-compose build                      # rebuild web container when new gems are installed
+docker-compose exec web pumactl restart   # restart Puma
+docker-compose exec web bin/rails console # access Rails console
+```
 
-# Or dynamically via the guard daemon
-bundle exec guard
+_Experienced Developers_
 
-# Leave that running while your server is running and
-# then press enter or update a page and the test suite will run
+The app can also run in your local development environment, but requires a bit more know-how.
 
-```
+1) [Install Postgres](https://www.postgresql.org/) (on MacOS try [Postgres.app](http://postgresapp.com/)).
 
-## Deploy
+2) Run the following commands:
 
 ```bash
-# This command will also copy your .env and .env.production to the server
-bundle exec cap production deploy
+git clone https://github.com/coyote-team/coyote.git
+cd coyote
+bin/setup
+bin/rails server && open http://localhost:3000
 ```
 
-## Update website images
-This uses each website's strategy (see below)
+The [seed script](https://github.com/coyote-team/coyote/blob/master/db/seeds.rb) builds a simple user, so you can login as `user@example.com`.
 
-```bash
-# Update images from past 2 minutes on local
-bin/rake websites:update
-# Update images from past 60 minutes on local
-bin/rake websites:update[60]
-# Update images from past 60 minutes on production
-TASK="websites:update[60]" bundle exec cap production rake
+We have setup a `Guardfile` to speed up development. Try `bundle exec guard`.
 
-```
+## <a name="documentation"></a> Documentation
+
+YARD documentation is hosted at [coyote-team.github.io](https://coyote-team.github.io/coyote/).
 
-## Heroku Deployment
+## <a name="heroku-deployment"> Heroku Deployment
 
 Requires installation of [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).
 
@@ -99,11 +102,9 @@ cd coyote
 heroku whoami # ensure you are logged-in
 heroku apps:create --name example-coyote-app-name
 
-# This line adds a free MySQL database to your app. They may still require you to enter a credit card before allowing this step.
-heroku addons:create jawsdb --as DATABASE --name coyote-production-mysql-db
-
 # this just runs "git push heroku", but we'll be adding bells and whistles
 # The first time you run this, it will take a while to install gems and prepare the environment
+
 bin/rake deploy 
 
 # Prepare the production database
@@ -125,49 +126,17 @@ herou logs --tail        # watch application log stream
 heroku run rails console # access production console
 ```
 
-## Docker Setup
-
-The app can run in a self-contained environment, which you can use for development.
-
-First, install [Docker Community Edition](https://www.docker.com/get-docker). Then:
-
-```bash
-docker-compose build # downloads images, builds containers
-docker-compose up    # start running containers
-docker-compose exec web bin/rake db:setup db:migrate db:seed                    # prepare database, add seed data
-docker-compose exec web bin/rake coyote:admin:create[user@example.com,password] # create initial user
-```
-
-The app should then be accessible at http://localhost:3000/. For more details see [local development with Docker Compose](https://devcenter.heroku.com/articles/local-development-with-docker-compose).
-
-## Docker Workflow
-
-```bash
-docker ps                                 # list running containers
-docker-compose build                      # rebuild web container when new gems are installed
-docker-compose exec web pumactl restart   # restart Puma
-docker-compose exec web bin/rails console # access Rails console
-```
-
-## API
+## <a name="api"> API
 
 API documentation is generated at `/apipie` and you can see MCA's version  [here](http://coyote.mcachicago.org/apipie).
 
-## Strategies
-We can extend the functionality of Coyote to better integrate with your particular CMS with a strategy file.  For an example, check out [/lib/coyote/strategies/mca.rb](https://github.com/coyote-team/coyote/blob/master/lib/coyote/strategies/mca.rb) 
+## <a name="strategies"> Strategies
 
-## Components
+We can extend the functionality of Coyote to better integrate with your particular CMS with a strategy file. For an example, check out [/lib/coyote/strategies/mca.rb](https://github.com/coyote-team/coyote/blob/master/lib/coyote/strategies/mca.rb).
 
-- [RubyOnRails](http://rubyonrails.org/)
-- [MariaDB](https://mariadb.org/) 
-- [rbenv](http://rbenv.org/) with [plugins](https://github.com/sstephenson/rbenv/wiki/Plugins) for gems, bundler, build, and binstubs
-- [bundler](http://bundler.io/)
-- [SASS](http://sass-lang.com/)
-- [Coffeescript](http://coffeescript.org/)
+## <a name="data-mode"> Data Model
 
-## Data model
-
-![Data model](datamodel.png)
+![Data model diagram](doc_assets/datamodel.png "An entity-relationship diagram demonstrating belongs-to/has-many relationships between database tables with connecting arrows")
 
 For use on [nomnoml](http://www.nomnoml.com/)
 
@@ -198,7 +167,7 @@ For use on [nomnoml](http://www.nomnoml.com/)
 
 Descriptions have an audit log that tracks changes across most columns.
 
-## Links
+## <a name="links"> Links
 
 - [Coyote repo](http://github.com/coyote-team/coyote)
 - [Coyote.pics](https://coyote.pics/)
@@ -212,21 +181,15 @@ More info regarding accessibility:
 - [ARIA in HTML](http://rawgit.com/w3c/aria-in-html/master/index.html) and [ARIA](http://www.w3.org/TR/wai-aria/states_and_properties#global_states)
 - [ABS's Guidelines for Verbal Description](http://www.artbeyondsight.org/handbook/acs-guidelines.shtml)
 
-## Coyote Admin
-- [Rollbar](https://rollbar.com/coyote/Coyote/)
-- [Google Analytics: Coyote MCA](https://analytics.google.com/analytics/web/#report/defaultid/a86309615w128502418p132251424/)
-
-## Versus
-- [Depict4](http://depictfor.us/)
-- [Autotune](https://github.com/voxmedia/autotune/)
+## <a name="contributors"> Contributors
 
-## Contributors
 - Tobey Albright, [MCA Chicago](https://mcachicago.org) - graphic design
 - Sina Bahram, [Prime Access Consulting](https://pac.bz/) - concept and direction
 - Susan Chun, [MCA Chicago](https://mcachicago.org) - project management
 - Anna Lavatelli, [MCA Chicago](https://mcachicago.org) - project management
 - Christopher Reed, [SEEREAD.info](http://seeread.info) - development
 - Mike Subelsky, [subelsky.com](http://subelsky.com) - development
 
-## License
+## <a name="license"> License
+
 [MPLv2](http://choosealicense.com/licenses/mpl-2.0/#)