#63 Update Jennifer Docs (#186)

* Updates base models README

* Updates jennifer/README

* Updates jennifer/model

* Jennifer/migrations

* Additional pass through

guides/models/README.md

@@ -1,16 +1,17 @@
 # Models
 
-Amber is independent of your choice of model architectures. We \(Core members\) have built the ORM **Granite**. We also think **Jennifer** built by [Roman Kalnytskyi](https://github.com/imdrasil) is a good option.
+The default ORM for Amber is [**Granite**](https://github.com/amberframework/granite), a lightweight Crystal ORM with adapters for MySQL, PostgreSQL and SQLite. Although Granite is the default configuration, the Amber framework supports alternate ORMs such as [**Jennifer**](https://github.com/imdrasil/jennifer.cr) built by [Roman Kalnytskyi](https://github.com/imdrasil) is a good option.
 
 ## Granite
 
-Granite provides a light weight ORM that is focused on taking the results of your query and mapping them to your model. It does not try to shield you from the SQL that lies underneath the mapping. It provides a couple conveniences like `save` and `destroy` for simple INSERT, UPDATE and DELETE statements. It provides `find`, `find_by` and `all` to query the database. It also has basic one-to-many relationships with `belong_to` and `has_many`.
+Granite provides a light weight ORM that is focused on taking the results of your query and mapping them to your model. It does not try to shield you from the SQL that lies underneath the mapping. Out of the box, Granite provides the several common search, read and write methods for your models such as `save`, `find_by`, `destroy`, _etc_, that map onto standard SQL INSERT, UPDATE and DELETE statements. Granite also supports basic one-to-many relationships with `belong_to` and `has_many` macros that will be familiar to developers experienced with ActiveRecord.
 
 [Granite Documentation](https://docs.amberframework.org/granite)
 
+
 ## Jennifer
 
-Jennifer provides an more full featured ORM with a full featured DSL for queries and follows the ActiveRecord pattern found in Rails. If you are looking for a full featured ORM, Jennifer may be your choice of ORM.
+Jennifer is a full featured ORM with a dedicate DSL that follows the ActiveRecord pattern found in Rails closely. If you are looking for a more full featured ORM Jennifer is a great choice.
 
 {% page-ref page="jennifer/" %}
 

guides/models/jennifer/README.md

@@ -2,49 +2,82 @@
 
 ## What is Jennifer?
 
-**Jennifer** is an ActiveRecord pattern for Crystal with great query DSL and migration mechanism.
+**Jennifer** is an ActiveRecord-like ORM for Crystal with a custom DSL for queries and migrations.
 
 {% hint style="info" %}
 This section is based on [Jennifer Docs](https://github.com/imdrasil/jennifer.cr/blob/master/docs/index.md). Also see [Amber Jennifer Example App](https://github.com/eliasjpr/amber-jennnifer-app-example).
 {% endhint %}
 
 ## Installing Jennifer for Amber
+By default, Amber applications ship with 
+[Granite](https://docs.amberframework.org/granite) a lightweight ORM for Crystal applications. To begin using Jennifer in your Amber application you will need to follow a few steps to get up and running.
 
 ### Generate a normal amber app
+Begin by generating a new amber project (if you have not already).
 
-```text
+```bash
 amber new {project}
+cd project
 ```
 
 ### Update your project shard.yml
+Once your Amber project is created, you will need to update your `shard.yml` file to include Jennifer as a dependency.
 
-Add this to your application's
+Add the following code snippet to your application's `shard.yml` file:
 
 ```yaml
-# Add the following dependencies
+# Jennifer is an ORM
 jennifer:
   github: imdrasil/jennifer.cr
 
+# SAM is a CLI utility for running migrations, creating or dropping tables
 sam:
   github: imdrasil/sam.cr
+
+```
+
+In addition to the Jennifer dependency, you may have noticed we included an additional shard called `sam`. The `sam` shard is simple command line utility for running common database tasks such as creating migrations, adding, or dropping tables. While technically optional it is recommended. 
+
+Once you've added the required dependencies, you will need to decide what database you would like to use with your Amber application. By default, Jennifer ships with SQLite support, however, should you want to use PostgreSQL or MySQL, you will need to add in a compatible database adapter to your `shard.yml` file. 
+
+```yaml
+# snipped shards 
+
+# Your choice of database adapter
+
+# PostgreSQL
+pg:
+	github: will/crystal-pg
+	version: "= 0.21.0"
+
+# MySQL
+crystal-mysql:
+	github: crystal-lang/crystal-mysql
+	version: "= 0.11.0"
 ```
 
-> Choose one of existing adapters for your db: [mysql](https://github.com/crystal-lang/crystal-mysql) or [postgres](https://github.com/will/crystal-pg).
+You can read about the Crystal community adapters below:
 
-Then in the console
+* [MySQL](https://github.com/crystal-lang/crystal-mysql) 
+* [PostgreSQL](https://github.com/will/crystal-pg).
 
-```text
+Once you have updated your dependencies and chosen an appropriate adapter (if any), proceed to update your project's shards by running:
+
+```bash
 shards update
 ```
 
+This command will begin installing Jennifer and its associated dependencies into your Amber project.
+
 ### Setup your database information
+Once Jennifer is up an running as a dependency in your project, you will need to create a new database configuration. Inside of your project's `config` directory create a new file called `config/database.yml` and fill in the code snippet below:
 
 ```yaml
 defaults : &defaults
   host: localhost
   adapter: postgres
-  user: root
-  password: somepassword
+  user: <add-your-database-user>
+  password: <add-your-database-password>
   migration_files_path: db/migrations # this is the default location for all migrations
 
 development:
@@ -56,7 +89,10 @@ test:
   <<: *defaults
 ```
 
-### Create a **jennifer.c**r under the **/config** directory
+The `config/database.yml` describes the various databases Jennifer will use in your project's different environments.
+
+### Add A Jennifer Initializer to Configuration
+With your `config/database.yml` in place, we need to inform Amber about Jennifer and tell the framework how we would like to configure the ORM. To begin, you will need to create a `config/jennifer.cr` file in your project's `config` directory. Below is a basic setup for Jennifer and you are also encourage to [see an example Amber Jennifer App] for more inspiration.
 
 ```ruby
 require "amber"
@@ -79,8 +115,9 @@ Note that we pass the `AMBER_ENV` to `Jennifer::Config.read` this will allow Jen
 {% endhint %}
 
 ### Create a sam.cr in {project/src}
+As mentioned previously, Jennifer uses Sam for running tasks pertinent to ORM operations. Sam is a Make-like utility which allows to specify tasks like Ruby's Rake do using plain Crystal. For how to use [Sam](https://github.com/imdrasil/sam.cr) visit the Github repository [https://github.com/imdrasil/sam.cr](https://github.com/imdrasil/sam.cr)
 
-Jennifer uses Sam for running tasks pertinent to ORM operations. Sam is a Make-like utility which allows to specify tasks like Ruby's Rake do using plain Crystal. For how to use [Sam](https://github.com/imdrasil/sam.cr) visit the Github repository [https://github.com/imdrasil/sam.cr](https://github.com/imdrasil/sam.cr)
+Create a new `sam.cr` file inside your project's `src` directory. 
 
 ```ruby
 # src/sam.cr
@@ -95,9 +132,10 @@ load_dependencies "jennifer"
 Sam.help
 ```
 
-### Edit your src/{project}.cr file
+This file operationalizes `sam` to begin running tasks. You can run `crystal sam.cr -- help` to get a list of available tasks once the file is added.
 
-This should be done before you load your application configurations \(or at least models\). With Amber this is very easy.
+### Including Jennifer in Server Bootstrap 
+The final step in configuration is to include Jennifer in your `src/{project}.cr` file. This should be done before you load your application configurations (or at least models). 
 
 ```ruby
 require "jennifer"

guides/models/jennifer/migrations.md

@@ -4,11 +4,11 @@
 This section is based on [Jennifer Docs](https://github.com/imdrasil/jennifer.cr/blob/master/docs/index.md).
 {% endhint %}
 
-To generate a migration run `crystal sam.cr generate:migration your_migration_name`
+To generate a migration run `crystal src/sam.cr generate:migration your_migration_name`
 
 ## Migration DSL
-
-Generator will create template file for you with next name pattern **timestamp\_migration\_name.cr**. Empty file looks like this:
+The generator will create template file for you with a consistent name pattern **timestamp\_migration\_name.cr**. 
+The empty file looks like this:
 
 ```ruby
 class YourCamelcasedMigrationName20170119011451314 < Jennifer::Migration::Base
@@ -20,7 +20,7 @@ class YourCamelcasedMigrationName20170119011451314 < Jennifer::Migration::Base
 end
 ```
 
-`up`method is needed for placing your db changes there, `down`- for reverting your changes back.
+The `up` method is where your database changes go, whereas, `down` is used for reverting your changes back.
 
 Example for creating table: