Enhances the docs for 'how it works'

docs/concepts/how-it-work.md

@@ -4,18 +4,51 @@ sidebar_position: 1
 
 # How it works
 
-Gitploy builds the system around GitHub [deployment API](https://docs.github.com/en/rest/reference/deployments#deployments). **It's an event-driven decoupled way to deploy your code.** Internally, Gitploy creates a new Github deployment resource, and Github dispatches a deployment event that external services can listen for and act. It enables developers and organizations to build loosely coupled tooling. 
+Gitploy builds the system around GitHub [deployment API](https://docs.github.com/en/rest/reference/deployments#deployments). Deployment API is a request to deploy a specific ref (branch, SHA, tag), and GitHub dispatches an event to deployment toolings that can listen for and act on when a request is posted. **It's an event-driven decoupled way to deploy your code.** This article looks under the hood Gitploy interacts with deployment API.
 
-This approach has several pros:
 
-* Replace deployment tools easily without changing your deployment pipeline. 
-* Easy to implement details of deploying different types of applications (e.g., web, native).
+## GitHub Deployment API
+
+The deployment API consists of these stages:
+
+1. A user selects a ref(branch, SHA, tag) to deploy.
+2. Gitploy verifies the ref for deployment safety.
+3. It requests GitHub to deploy a specific ref. 
+
+Of course, Gitploy follows these stages to deploy a ref and enhances each stage to use it easily and safely.
+
+### Select a ref(branch, SHA, tag)
+
+A ref can be any named branch, tag, or SHA, and it is determined by how to deploy an application. If an application uses semantic versioning, the ref should be a tag(e.g., `v0.5.5`).
+
+Gitploy provides an intuitive UI similar to GitHub, enabling users to select a ref easily even though a user is a newcomer to the system. And it displays the details of a commit such as SHA, message, creator, and creation time. So it enables to let users know which commits are deployed.
+
+### Verification
+
+Before deploying a ref, it needs verification for deployment safety. The deployment API provides these verifications: 
+
+* `auto_merge`: Ensure that the requested ref is not behind the repository's default branch. 
+* `required_contexts`: Ensure that commit statuses are in that success state.
+
+Gitploy provides the file (i.e., `deploy.yml`) to configure the parameters for each runtime environment, respectively. 
+
+### Event Dispatch
+
+Gitploy posts a request to GitHub, and it dispatches an event to deployment toolings.
+
+## Deployment Tooling
+
+### Update status
+
+After deployment, a deployment tooling must update the deployment status if it has succeeded or not by the [deployment status API](https://docs.github.com/en/rest/reference/deployments#deployment-statuses). It enables Gitploy to sync the deployment status and display the deployment status with a redirection link for the deployment details, such as logs.
+
+![Deployment statuses](../../static/img/docs/statuses.png)
 
 Below is a simple diagram for how these interactions would work:
 
 ```
 +---------+             +--------+             +---------+         +-------------+
-| Gitploy |             | GitHub |             |  Tools  |         | Your Server |
+| Gitploy |             | GitHub |             | Tooling |         | Your Server |
 +---------+             +--------+             +---------+         +-------------+
      |                      |                       |                     |
      |  Create Deployment   |                       |                     |
@@ -31,18 +64,16 @@ Below is a simple diagram for how these interactions would work:
      |                      |                       |                     |
      |                      |   Deployment Status   |                     |
      |                      |<----------------------|                     |
-     |   Deployment Status  |                       |                     |
-     |<---------------------|                       |                     |
+     |                      |                       |                     |
+     |                      |                       |                     |
      |                      |                       |                     |
      |                      |                       |   Deploy Completed  |
      |                      |                       |<--------------------|
      |                      |   Deployment Status   |                     |
      |                      |<----------------------|                     |
-     |   Deployment Status  |                       |                     |
-     |<---------------------|                       |                     |
+     |                      |                       |                     |
+     |                      |                       |                     |
      |                      |                       |                     |
 ```
 
-Gitploy lets you can build the advanced deployment system so your team and organization enable to deploy the application with lower risk and faster.
-
 *Keep in mind that Gitploy is never actually accessing your servers. It's up to your tools to interact with deployment events.*

docs/index.md

@@ -3,7 +3,7 @@ sidebar_position: 1
 title: What is Gitploy?
 ---
 
-Gitploy is a tooling that helps your organization build the deployment system in minutes. It enables your organization **to deploy in the same manner** without worrying about the details of different types of applications and **to deploy differently** for each application, respectively. And as a result, your organization can get a robust system to deploy fast and safely. 🚀
+Gitploy is a tooling that helps your organization build the deployment system in minutes. It enables your organization **to deploy in the same manner** without worrying about  the implementation details of delivering different types of applications (e.g., web, native). and **to deploy differently** for each application by a simple configuration file, respectively. And as a result, your organization can get a robust system to deploy fast and safely. 🚀
 
 ## Deploy in the same manner
 
@@ -19,7 +19,7 @@ Gitploy provides an intuitive UI similar to GitHub. Users can select one of the
 
 ## Deploy differently
 
-Each application needs a customizable pipeline. If an organization has essential applications to deploy carefully, it should enforce a gateway like a review or deploy freeze window. And an organization chooses continuous delivery or continuous deployment for application.
+Each application needs a customizable pipeline. If an organization has essential applications to deploy carefully, it should enforce a gateway like a review or deploy freeze window. And also an organization chooses continuous delivery or continuous deployment for application.
 
 Gitploy provides a way **to configure a pipeline with a simple, easy‑to‑read file for each repository (each environment).** The default path is `deploy.yml` at the root directory, but you can replace the file path in the settings tab of Gitploy.