#63 Cleans up Configuration Docs

guides/configuration.md

@@ -1,44 +1,75 @@
 # Configuration
 
-Your Amber project has a `{project_name}/config` directory, this directory contains Amber configuration files.
+Every Amber project has a `{project_name}/config` directory. This directory contains all the configuration files used by your Amber project.
 
-## Default Environments
+## Configuring Amber
+
+Within the `config` directory of an Amber project, you will find several helpful configuration settings.
 
-Your Amber project ships with three default environments:
+### Environments
+Each Amber project ships with three default environments:
 
 * Development 
 * Test
 * Production 
 
-The files for each of the environment is found in `{project_name}/config/environments`.
+The files for each environment are found under `{project_name}/config/environments`. Each Amber environment is configured in separate YAML files under this directory. 
+
+At runtime the framework will use the `AMBER_ENV` environment value to load the respective environment configuration into the application. For example if `AMBER_ENV=staging` the framework will expect a `config/environments/staging.yml` file to exist and attempt to load its configurations into the application.
 
 ## Getting the current environment
 
-To get the current amber environment just type `Amber.env.to_s`. You can also check against the current environment `Amber.env== :production` or `Amber.env.development?` `Amber.env.test?` `Amber.env.production?`
+To get the current Amber environment you can use the `Amber.env` method. 
+
+```ruby
+Amber.env
+# returns => :production
+```
+
+Alternatively, you can use built in environment helpers such as `Amber.env.development?`, `Amber.env.test?`, and `Amber.env.production?` to check the environment value.
 
 ## Setting the current environment
 
-Amber sets the current environment based on the `AMBER_ENV` environment variable. The default environment is `development`.
+As mentioned previously, Amber sets the application environment based on the `AMBER_ENV` environment variable. By default, the environment is set to `development`. If you would like to set the environment to something else, you will need to configure the `AMBER_ENV` environment variable before running the server process.
 
-## Configuring Amber
+For example to run Amber in the production environment, we can set the `AMBER_ENV` to `production`. 
 
-All amber project have a directory called `config/` in this directory you will find
+```bash
+AMBER_ENV=production amber watch
+```
 
 ### Initializers
 
-You can use initializers to hold configuration settings that should be made after all of the frameworks and shards are loaded, such as options to configure settings for these parts.
+You can use initializers to load configuration settings into various application components like mailers after all of the frameworks and shards are loaded. 
 
-`config/initializers`place any initializer file here to load at runtime.
+To add a new initializer simply create a file and save it under `config/initializers` to load at runtime.
 
-### Environments
+For example, to initialize a `Quartz` mailer:
+
+```ruby
+# config/initializers/mailer.cr
 
-`config/environments` all your environment YAML configuration files live here, these files get loaded based on the `AMBER_ENV` value. For example `AMBER_ENV=staging` then this will expect a `config/environments/staging.yml` file to exist.
+require "quartz_mailer"
+
+Quartz.config do |c|
+  c.smtp_enabled = Amber.settings.smtp.enabled
+
+  c.smtp_address = ENV["SMTP_ADDRESS"]? || Amber.settings.smtp.host
+  c.smtp_port = ENV["SMTP_PORT"]? || Amber.settings.smtp.port
+  c.username = ENV["SMTP_USERNAME"]? || Amber.settings.smtp.username
+  c.password = ENV["SMTP_PASSWORD"]? || Amber.settings.smtp.password
+
+  c.use_authentication = !c.password.blank?
+end
+```
 
 ### Application.cr
 
-`config/application.cr` this is the main entry file for amber application files and it allows you to overwrite setting based on dynamic values, it makes it possible to use environment variables as your settings.
+The main entry point for an Amber application is `config/application.cr`. This application file allows you to overwrite settings using dynamic values. It also allows you to use environment variables available to the application process to configure your application.
 
 ```ruby
+# config/application.cr 
+
 Amber::Server.configure do |app|
   app.name = ENV["APP_NAME"] if ENV["APP_NAME"]?
   app.host = ENV["HOSTNAME"] if ENV["HOSTNAME"]?
@@ -49,9 +80,11 @@ end
 
 ## Where do custom settings go?
 
-You can include new settings in any of the environment YAML files by specifying them in the secrets section.
+Amber makes it easy to manage custom settings in each of the environment YAML files. You can include new settings in any of the environment YAML file by specifying them in the secrets section.
 
 ```yaml
+# config/environments/development.yml
+
 database_url: postgres://postgres:@localhost:5432/test_development
 secrets: 
   custom: secret value here
@@ -67,9 +100,13 @@ Amber.settings.secrets["custom"] # =>  "secret value here"
 
 ## Encrypted Environment Settings
 
-With Amber you can encrypt your environment setting `amber encrypt {environment}`, this command will open your editor to allow make changes if needed and then encrypt the file `{environment}.enc`.
+With Amber you can encrypt your environment setting using `amber encrypt {environment}`, this command will open your editor to allow make changes if needed and then encrypt the file `{environment}.enc`.
 
-A `.encryption_key` file is provided. It contains a secret\_key\_base that is used to decrypt your encrypted environment settings. This file is added to `.gitignore` so it will not be committed to your repository. Without the encryption key, you won't be able to decrypt your environment settings.
+A `.encryption_key` file is provided. It contains a `secret_key_base` that is used to decrypt your encrypted environment settings. This file is added to `.gitignore` to avoid inclusion in version control. 
+
+{% hint style="danger" %}
+Without the encryption key, you won't be able to decrypt your environment settings.
+{% endhint %}
 
 {% hint style="danger" %}
 **Never commit the encryption key!**
@@ -78,6 +115,3 @@ Setup your production machine and use the variable `AMBER_ENCRYPTION_KEY`
 
 See more on [encrypt section](../cli/encrypt.md)
 {% endhint %}
-
-
-