Reviews guides/installation, directory structure, routing

guides/directory-structure.md

@@ -1,8 +1,6 @@
 # Directory Structure
 
-A generated Amber app has a number of auto-generated files and folders that make up the structure of an Amber application.
-
-When you use the `amber new` command to create your application, it creates the entire directory structure for the application, because of this Amber knows where to find the files it needs within this structure, so you don't have to provide additional input.
+Every Amber app is generated with a variety of default files and folders that make up the structure of the application. When you run `amber new` to create your application, you will see that the Amber CLI creates the entire directory structure for the application for you to use. The table below details out the variety of files and folders created in the generation process as well as their purpose.
 
 | File Folder | Purpose |
 | :--- | :--- |

guides/installation.md

@@ -4,7 +4,7 @@ description: That feeling you get when that right tool did all the work
 
 # Installation
 
-Amber CLI offers you a set of command line tools to **create**, **generate**, **scaffold** and **run** your projects easily and fast.
+The Amber CLI offers you a set of command line tools to **create**, **generate**, **scaffold** and **run** your projects quickly and simply.
 
 ## Linux
 
@@ -28,7 +28,7 @@ make
 sudo make install
 ```
 
-If you run into an issue on compiling regarding `Unhandled exception in spawn: fork: Cannot allocate memory` it means you don't have enough memory. This can easily be solved by adding a swapfile.
+If you run into an issue on compilation regarding `Unhandled exception in spawn: fork: Cannot allocate memory` it means you don't have enough memory. This can easily be solved by adding a swapfile.
 
 ```bash
 sudo dd if=/dev/zero of=/swapfile bs=2k count=1024k

guides/overview.md

@@ -1,28 +1,28 @@
 # Overview
 
-Amber is designed to make everyday web-development tasks simple, and comfortable, maintaining developer engagement, productivity without performance penalties. By providing an all-in-one toolbox to get you started the various parts of Amber work well together or separately.
+Amber is designed to make everyday web-development simple and comfortable by maintaining developer engagement and productivity without performance penalties. By providing an all-in-one toolbox, Amber gives developers the leverage to begin developing complex web applications from day one.
 
-The goal of this overview is to introduce the general concepts in Amber and give you a quick overview of how those concepts are implemented in Amber.
+The goal of this overview is to introduce the general concepts in Amber and give you a quick overview of how those concepts are implemented.
 
 ## Conventions Over Configuration
 
-Amber provides a basic organizational structure that covers class names, filenames, database table names, and other conventions. While the conventions take some time to learn, by following the conventions Amber provides you can avoid needless configuration and make a uniform application structure that makes working with various projects simple.
+Amber provides a opinionated organizational structure that covers class names, file names, database table names, and other conventions. While these conventions can take some time to learn, by following Amber's convention over configuration philosophy you can avoid needless configuration decisions, and ensure a uniform application architecture that makes working across various projects and with multiple developers simple.
 
 ## Model-View-Controller
 
 Model–view–controller \(MVC\) is a software architectural pattern for implementing user interfaces on computers. It divides a given application into three interconnected parts. The division is done to separate internal representations of information from the way information is presented to, and accepted from, the user. The MVC design pattern decouples these significant components allowing for efficient code reuse and parallel development.
 
 ### Advantages
 
-* Simultaneous development – Multiple developers can work simultaneously on the model, controller, and views..
-* High cohesion – MVC enables logical grouping of related actions on a controller together. The views for a specific model are also grouped.
-* Low coupling – The very nature of the MVC framework is such that there is low coupling among models, views or controllers.
-* Ease of modification – Because of the separation of responsibilities, future development or change is easier.
-* Multiple representations for a model – Models can have various Views.
+* **Simultaneous development** – multiple developers can work simultaneously on the model, controller, and views.
+* **High cohesion** – MVC enables logical grouping of related actions on a controller together. The views for a specific model are also grouped.
+* **Low coupling** – the MVC pattern ensures low coupling between models, views or controllers.
+* **Ease of modification** – because of the separation of responsibilities, future development or change is easier.
+* **Multiple representations for a model** – models can have various views.
 
 ### Controller Layer
 
-The Controller is responsible for controlling the application logic and acts as the coordinator between the View and the Model. The Controller receives an input from the users via the View, then processes the user's data with the help of Model and passes the results back to the View.
+The Controller is responsible for directing application logic. It does this by acting as the coordinator between the other two components. The Controller receives an input from the users via the View, then processes the user's data with the help of Model and passes the results back to the View.
 
 ```ruby
 class UsersController < ApplicationController
@@ -35,7 +35,7 @@ end
 
 ### View Layer
 
-Views are the component involved with the application's User Interface. These Views are generally bound from the model data and have extensions such as HTML, SLANG, ECR.
+Views are the component involved with the application's User Interface. Views are generally populated with model data and have extensions such as HTML, SLANG, ECR.
 
 ```ruby
 # Slang - /views/users/index.slang
@@ -57,9 +57,11 @@ html
 
 ### Model Layer
 
-The Model layer represents the part of your application that implements the business logic. It is responsible for retrieving data and converting it into the first meaningful concepts in your web application. Includes processing, validating, associating or other tasks related to handling data.
+The Model layer represents the central data component of your application and implements the business logic and rules which govern it. The model is responsible for providing a clear interface for your web application to read from and manipulate user data. Such manipulations include processing changes, validating, creating associations to other models and more.
 
-In the case of a social network, the Model layer would take care of tasks such as saving the user data, saving friends’ associations, storing and retrieving user photos, finding suggestions for new friends, etc. The model objects are the main components of your application, such as “Friend,” “User,” “Comment,” or “Photo.” If we wanted to load some data from our user's table we could do:
+In the case of a social network, the Model layer would take care of tasks such as saving user data, saving friends’ associations, storing and retrieving user photos, finding suggestions for new friends, and more. The model objects are the main entities of your application, such as “Friend,” “User,” “Comment,” or “Photo.” 
+
+For example:
 
 ```ruby
 class User
@@ -70,4 +72,3 @@ class User
   end
 end
 ```
-

guides/routing/README.md

@@ -4,13 +4,13 @@ The Amber router recognizes URLs and dispatches them to a controller's action. I
 
 ## Pipelines
 
-A _pipeline_ is a set of of transformations that is performed to a HTTP request. These transformations come in the form of a pipe. A _pipe_ is a _\*\*_class which includes [`HTTP::Handler`](https://crystal-lang.org/api/latest/HTTP/Handler.html) and implements the [`#call`](https://crystal-lang.org/api/latest/HTTP/Handler.html#call%28context%3AHTTP%3A%3AServer%3A%3AContext%29-instance-method) method. You can use a handler to intercept any incoming request and modify the response. These can be used for request throttling, ip-based whitelisting, adding custom headers.
+A _pipeline_ is a set of of transformations that is performed on an HTTP request. These transformations come in the form of a pipe. A _pipe_ is a _\*\*_class which includes [`HTTP::Handler`](https://crystal-lang.org/api/latest/HTTP/Handler.html) and implements the [`#call`](https://crystal-lang.org/api/latest/HTTP/Handler.html#call%28context%3AHTTP%3A%3AServer%3A%3AContext%29-instance-method) method. You can think of a pipe as a form of middleware that intercepts any incoming request and modifies the response. Some example usages for pipes are request throttling, ip-based whitelisting, adding custom headers.
 
 {% page-ref page="pipelines.md" %}
 
 ## Routes
 
-Routing provides you tools that map URLs to controller actions. By defining routes, you can separate how your application is implemented from how its URL’s are structured, Routes wire up real-time web socket handlers, and define a series of pipeline transformations for scoping middleware to sets of routes.
+Routing in Amber provides developers a manifest to map application URLs to controller actions. By defining routes, you can separate how your application directs requests and how URLs are structured. Each route creates a real-time web socket handler, and define a series of pipeline transformations for scoping middleware to sets of routes.
 
 {% page-ref page="routes.md" %}
 

guides/routing/routes.md

@@ -1,8 +1,7 @@
 # Routes
+Routing in Amber provides developers a manifest to map application URLs to controller actions. By defining routes, you can separate how your application directs requests and how URLs are structured. Each route creates a real-time web socket handler, and define a series of pipeline transformations for scoping middleware to sets of routes.
 
-Routing provides you tools that map URLs to controller actions. By defining routes, you can separate how your application is implemented from how its URL’s are structured. Routes wire up real-time web socket handlers, and define a series of pipeline transformations for scoping middleware to sets of routes.
-
-A route connects a HTTP request to an action inside a controller. When your Amber application receives an incoming request for: `GET /users/24` it asks the Amber router to match it to a controller action. If the router finds a match `get users/:id, UsersController, :index` the request is dispatched to the UsersController.index action with { id: 24 } in the params hash.
+A route connects a HTTP request to a function inside a controller. When your Amber application receives an incoming request for: `GET /users/24` it asks the Amber router to find the corresponding controller action to direct the request towards. If the router finds a match, for example `get users/:id, UsersController, :index`, the request will be dispatched to the matching method with the provided parameters, in this case the UsersController.index action with { id: 24 } in the params hash.
 
 ## Configuring Routes
 
@@ -20,46 +19,52 @@ end
 
 ## Defining Routes
 
-The **routes** macro accepts a **pipeline** name and a **scope**, in which all routes defined within this block will make use of the pipeline and the url will be scoped.
+The **routes** macro accepts a **pipeline** name and a **scope**. In addition to the pipeline and scope, the routes macro also takes an additional block parameter where you can define routes. All routes defined within a scope's block will make use of the provided pipeline and the URLs will be scoped accordingly.
 
-Lets say you are defining a static website and you want the URL to be displayed as `http://www.mycoolsite.com/page`. You will define your routes as:
+For example, let's say you are creating a static website and you want the URL to be displayed as `http://www.mycoolsite.com/page`. To do this, you would setup your routes as follows:
 
 ```ruby
 # routes(pipeline, scope)
 routes :web, "/page"
 ```
 
-The routes macro takes a last argument. And a block within the block is where you define your routes.
+If you wanted to created a namespace for nesting your URL routes, you can use the scope parameter to do so.
 
 ```ruby
-routes :web, '/static' do
+routes :web, '/v1' do
   get "/about", StaticController, :about
 end
 ```
 
 Mapping the above route
 
-| Http Method | Resource | Controller | Action |
+| Http Method | Path | Controller | Action |
 | :--- | :--- | :--- | :--- |
-| get | "/about" | StaticController | :about |
+| get | "/v1/about" | StaticController | :about |
 
-Your action will need to return a string or render a view or this will cause your routes to throw an error during compilation.
+Your controller action will need to return a string or render a view. If no string or view is rendered your routes configuration will raise an error during compilation.
 
 ```ruby
-def about
-  "About my cool page!"
-end
+class StaticController < ApplicationController
+	 def about
+		 "About my cool page!"
+	 end
 
-# or:
+	 # or:
 
-def about
-  render("about.ecr")
+	 def about
+		 render("about.ecr")
+	 end
 end
 ```
 
 ## Resources
 
-The router supports other macros besides those for HTTP verbs like _get_, _post_, and _put_. The most important among them is `resources`, which expands out to eight endpoints.
+The router supports other macros besides those for HTTP verbs like _get_, _post_, and _put_. The most important among them is `resources`. The `resources` macro is a quick way to setup up resourceful routing for all seven standard actions for a controller in a single line. 
+
+{% hint style="info" %}
+In order to use resourceful routing for a particular controller, your controller _must_ define and implement all seven standard actions: `index`, `edit`, `new`, `show`, `create`, `destroy`, and `update`. If your controller does not implement all seven actions, an error will be raised during compilation.
+{% endhint %}
 
 Let’s add a resource to the `config/routes.cr`
 
@@ -71,7 +76,7 @@ end
 
 Then go to the root of your project, and run `amber routes`
 
-It outputs the standard matrix of HTTP verbs, controller, action, pipeline, scope, and URI pattern.
+This will output the standard matrix of HTTP verbs, controller, action, pipeline, scope, and URI pattern.
 
 ![Amber Routes Matrix Example](https://raw.githubusercontent.com/amberframework/site-assets/master/images/amber_routes.png)