Clarify the docs for newcomers more

Hummingbird.docc/Articles/EncodingAndDecoding.md

@@ -5,7 +5,9 @@
 }
 
 
-Hummingbird uses `Codable` to decode requests and encode responses. 
+Hummingbird uses `Codable` to decode requests and encode responses. Codable is a flexible, type-safe way to encode and decode data from various formats.
+
+Hummingbird provides a JSON-based solution out-of-the-box, but also provides support for URL-encoded form data. In addition, other Codable libraries can be used with Hummingbird by implementing the ``RequestDecoder`` and ``ResponseEncoder`` protocols.
 
 The request context ``RequestContext`` that is provided alongside your ``/HummingbirdCore/Request`` has two member variables ``RequestContext/requestDecoder`` and ``RequestContext/responseEncoder``. These define how requests/responses are decoded/encoded. 
 

Hummingbird.docc/Articles/GettingStarted.md

@@ -9,11 +9,12 @@ Create a new project on GitHub or an app locally from a starter template.
 ## Overview
 
 The Hummingbird project provides multiple entry points for getting started.
-Create your own project that uses Hummingbird from a [starting template](https://github.com/hummingbird-project/template) to jump right in.
-For a walk-through building an application with Hummingbird, explore and follow along the [Build a Todos Application](https://docs.hummingbird.codes/2.0/tutorials/todos) tutorial.
-Take some time to explore the [hummingbird examples](https://github.com/hummingbird-project/hummingbird-examples/), individual project snapshots that use common application patterns.
 
-### Creating a new local project from the starting template
+1. Create your own project that uses Hummingbird from a [starting template](https://github.com/hummingbird-project/template) to jump right in.
+2. For a walk-through, explore and follow along the [Build a Todos Application](https://docs.hummingbird.codes/2.0/tutorials/todos) tutorial.
+3. Take some time to explore the [Hummingbird Examples](https://github.com/hummingbird-project/hummingbird-examples/), individual projects that use common patterns.
+
+### Creating a project locally
 
 Clone the starting template to your local machine:
 
@@ -33,10 +34,14 @@ Then run your app:
 
 The starting template is also designed so that you can create a new GitHub repository from it.
 
-### Creating a new GitHub repository from the template
+### Create using GitHub template
 
 - Sign in to GitHub.
-- Navigate to https://github.com/hummingbird-project/template.
+- Navigate to [https://github.com/hummingbird-project/template](https://github.com/hummingbird-project/template).
 - Click "Use this template" and create your new repository.
 - Clone the repository to a codespace or your local machine.
 - Run the configuration script (`./configure.sh`) to configure your new project.
+
+### Next Steps
+
+Follow our TODO's application to get started with the framework: <doc:Todos>

Hummingbird.docc/Tutorials/Todos/Todos-2-API.tutorial

@@ -16,7 +16,7 @@
                 @Code(name: "Sources/App/Controllers/TodoController.swift", file: todos-api-01.swift)
             }
             @Step {
-                Go back to `buildRouter()` in Application+build.swift
+                Go back to `buildRouter()` in Application+build.swift. Routers ensure a Request is _routed_ to the correct handler function.
                 @Code(name: "Sources/App/Application+build.swift", file: todos-template-06.swift)
             }
             @Step {
@@ -31,35 +31,35 @@
                 @Code(name: "Sources/App/Repositories/Todo.swift", file: todos-api-03.swift)
             }
             @Step {
-                We are going to use `Todo` as the return value for some of our routes, so it needs to conform to `ResponseEncodable`. Later we will also be using it in tests so lets add `Decodable` and `Equatable` conformances.
+                We are going to use `Todo` as the return value for some of our routes, so it needs to conform to `ResponseEncodable`. This allows us to return it from our routes and have it automatically encoded as JSON. Later we will also be using it in tests so lets add `Decodable` and `Equatable` conformances, for reading JSON and comparing todos.
                 @Code(name: "Sources/App/Repositories/Todo.swift", file: todos-api-04.swift)
             }
             @Step {
-                Create a `TodoRepository` protocol that defines all the methods to manage todos: (get, list, create, update, delete and deleteAll).
+                Create a `TodoRepository` protocol that defines all the methods to manage todos: (get, list, create, update, delete and deleteAll). This allows us to use a different implementation of the repository for different storage methods.
                 @Code(name: "Sources/App/Repositories/TodoRepository.swift", file: todos-api-05.swift)
             }
             @Step {
-                Create a concrete implementation of `TodoRepository` protocol that saves everything to memory. We use an actor because multiple tasks could be accessing the repository at the same time.
+                Create a concrete implementation of `TodoRepository` protocol that saves everything to memory. We use an actor because multiple tasks could be accessing the repository at the same time, and actors are thread safe.
                 @Code(name: "Sources/App/Repositories/TodoMemoryRepository.swift", file: todos-api-06.swift)
             }
             @Step {
                 Return to TodoController.swift
                 @Code(name: "Sources/App/Controllers/TodoController.swift", file: todos-api-01.swift)
             }
             @Step {
-                And add a generic repository member variable conforming to `TodoRepository` to be used by the `TodoController` routes.
+                And add a generic repository member variable conforming to `TodoRepository` to be used by the `TodoController` routes. Generics allow us to use the same controller for different repository implementations.
                 @Code(name: "Sources/App/Controllers/TodoController.swift", file: todos-api-07.swift)
             }
             @Step {
                 Go to `buildRouter()` in Application+build.swift
                 @Code(name: "Sources/App/Application+build.swift", file: todos-api-02.swift)
             }
             @Step {
-                And add the repository parameter to the TodoController initializer. We are using the memory implementation of the `TodoRepository` we have already implemented above.
+                And add the repository parameter to the TodoController initializer. We are using the memory implementation of the `TodoRepository` we have already implemented previously.
                 @Code(name: "Sources/App/Application+build.swift", file: todos-api-08.swift)
             }
             @Step {
-                Return to TodoController.swift. We can now start adding our endpoints.
+                Return to TodoController.swift. We can now start adding our endpoints. An endpoint (or Route) is a function that replies to a request if the path and method match.
                 @Code(name: "Sources/App/Controllers/TodoController.swift", file: todos-api-07.swift)
             }
             @Step {
@@ -73,7 +73,7 @@
                 @Code(name: "Sources/App/Controllers/TodoController.swift", file: todos-api-09.swift)
             }
             @Step {
-                Our second endpoint is to create a Todo. We have added a struct to decode from the request. In a similar way the get endpoint response uses JSONEncoder to generate its response, this uses the JSONDecoder attached to the context. We then call the repository `create` method and return the result.
+                Our second endpoint is to create a Todo. We have added a struct to decode from the request. In a similar way the get endpoint response uses JSONEncoder to generate its response, this uses the JSONDecoder attached to the context to read JSON from the request. We then call the repository `create` method and return the result.
                 @Code(name: "Sources/App/Controllers/TodoController.swift", file: todos-api-10.swift)
             }
             @Step {

Hummingbird.docc/index.md

@@ -9,7 +9,9 @@ Documentation for Hummingbird the lightweight, flexible, modern server framework
 
 ## Hummingbird
 
-Hummingbird is a lightweight and flexible web application framework. It provides a router for directing different endpoints to their handlers, middleware for processing requests before they reach your handlers and processing the responses returned, custom encoding/decoding of requests/responses, TLS and HTTP2.
+Hummingbird is a lightweight and flexible web application framework. It provides a router for directing different endpoints to their handlers, middleware for processing requests before they reach your handlers and processing the responses returned, custom encoding/decoding of requests and responses, TLS and HTTP2.
+
+If you're new to Hummingbird, start here: <doc:Todos>
 
 ```swift
 import Hummingbird