Update documentation, improve language, fix grammar and typos (#3657)

docs/KNOWN_BUGS.md

@@ -2,9 +2,9 @@
 
 ## Ubuntu 14.04, Coreutils 8.21
 
-There are known bug with relative symlinks `ln --relative`, which may fail rollback command.
+There are known bugs with relative symlinks `ln --relative`, which may cause the rollback command to fail.
 
-Add next line to _deploy.php_ file:
+Add the following line to your _deploy.php_ file:
 
 ```php
 set('use_relative_symlink', false);

docs/basics.md

@@ -15,17 +15,17 @@ $ dep deploy deployer.org
    `------------------ CLI
 ```
 
-Deployer uses the [selector](selector.md) to choose hosts. Next takes the given
+Deployer uses the [selector](selector.md) to choose hosts. Next, it takes the given
 task, performs some preparation (described later), and executes the task on all
 selected hosts.
 
-If selector not specified Deployer will ask you to choose host from list.
+If a selector is not specified, Deployer will ask you to choose a host from a list.
 If your recipe contains only one host, Deployer will automatically choose it.
-To select all hosts specify a special selector: `all`.
+To select all hosts, specify a special selector: `all`.
 
-The `dep` CLI looks for `deploy.php` or `deploy.yaml` file in current directory.
+The `dep` CLI looks for a `deploy.php` or `deploy.yaml` file in the current directory.
 
-Or recipe can be specified explicitly via `-f` or `--file` option.
+Or a recipe can be specified explicitly via `-f` or `--file` option.
 
 ```
 $ dep --file=deploy.php deploy deployer.org
@@ -34,8 +34,8 @@ $ dep --file=deploy.php deploy deployer.org
 Let's write a recipe.
 
 ```php
-// We are going to use functions declared primarily in Deployer namespace,
-// to simplify recipe we will use Deployer namespace too. Alternativly,
+// We are going to use functions declared primarily in the Deployer namespace,
+// to simplify the recipe, we will also use the Deployer namespace. Alternatively,
 // you can import individual functions via "use function".
 namespace Deployer;
 
@@ -55,7 +55,7 @@ $
 ```
 
 But where is our `whoami` command output? By default, Deployer runs with normal verbosity
-level and shows only names of executed tasks. Let's increase verbosity to verbose, and
+level and shows only the names of executed tasks. Let's increase verbosity to verbose, and
 rerun our task.
 
 Add `-v` option to increase verbosity. Read more about [CLI usage](cli.md).
@@ -68,15 +68,15 @@ task my_task
 $
 ```
 
-Now let's add second host:
+Now let's add a second host:
 
 ```php
 host('deployer.org');
 host('medv.io');
 ```
 
-How does Deployer know how to connect to a host? It uses same `~/.ssh/config` file as
-the `ssh` command. Alternatively, you can specify [connection options](hosts.md) in recipe.
+How does Deployer know how to connect to a host? It uses the same `~/.ssh/config` file as
+the `ssh` command. Alternatively, you can specify [connection options](hosts.md) in the recipe.
 
 Let's run `my_task` task on both hosts:
 
@@ -101,7 +101,9 @@ task my_task
 [medv.io] deployer
 ```
 
-Limit level also possible to [specified per task](tasks.md#limit).
+It is also possible to specify a [limit level](tasks.md#limit) for each individual task.
+By specifying the limit level for each task, you can control the degree of parallelism 
+for each part of your deployment process.
 
 Each host has a configuration: a list of key-value pairs. Let's define our first
 configuration option for both our hosts:
@@ -113,7 +115,7 @@ host('medv.io')
     ->set('my_config', 'bar');
 ```
 
-In the task we can get current executing host with [currentHost](api.md#currenthost) function:
+In the task we can get the currently executing host using the [currentHost](api.md#currenthost) function:
 
 ```php
 task('my_task', function () {
@@ -122,7 +124,7 @@ task('my_task', function () {
 });
 ```
 
-Or with [get](api.md#get) function:
+Or with the [get](api.md#get) function:
 
 ```diff
 task('my_task', function () {
@@ -132,11 +134,11 @@ task('my_task', function () {
 });
 ```
 
-Or via [parse](api.md#parse) function which replaces brackets `{{ ... }}` and value
-with of config option.
+Or via the [parse](api.md#parse) function which replaces the `{{ ... }}` brackets 
+and their enclosed values with the corresponding configuration option.
 
-All functions (writeln, run, runLocally, cd, upload, etc) call **parse** function
-internally. So you don't need to call **parse** function by your self.
+All functions (writeln, run, runLocally, cd, upload, etc) call the **parse** function
+internally. So you don't need to call the **parse** function by yourself.
 
 ```diff
 task('my_task', function () {
@@ -167,8 +169,9 @@ host('medv.io');
 
 The config option `my_config` will be equal to `global` on both hosts.
 
-Also, config option value can be specified as a callback, such callback
-executed on first access and returned result saved in host configuration.
+Additionally, the value of a config option can be defined as a callback. 
+This callback is executed upon its first access, and the returned result 
+is then stored in the host configuration.
 
 ```php
 set('whoami', function () {
@@ -189,9 +192,11 @@ task my_task
 [medv.io] Who am I? anton
 ```
 
-We can use this to create dynamic configuration which uses current host information.
+We can use this to create a dynamic configuration which uses information from the current host.
+
+Only the first call will trigger the callback execution. All subsequent checks use the previously 
+saved value.
 
-Only the first call will trigger the callback execution. All subsequent checks use saved value.
 
 Here is an example:
 
@@ -207,7 +212,7 @@ task('my_task', function () {
 });
 ```
 
-If we run my_task we will see that `date` is called only once on
+If we run my_task, we will see that `date` is called only once on
 `{{current_date}}` access.
 
 ```

docs/ci-cd.md

@@ -44,15 +44,15 @@ deploys.
 
 ## GitLab CI/CD
 
-Set the following variables in GitLab project:
+Set the following variables in your GitLab project:
 
 - `SSH_KNOWN_HOSTS`: Content of `~/.ssh/known_hosts` file.
   The public SSH keys for a host may be obtained using the utility `ssh-keyscan`.
   For example: `ssh-keyscan deployer.org`.
 - `SSH_PRIVATE_KEY`: Private key for connecting to remote hosts.
-  To generate private key: `ssh-keygen -t ed25519 -C 'gitlab@deployer.org'`.
+  To generate a private key: `ssh-keygen -t ed25519 -C 'gitlab@deployer.org'`.
 
-Create .gitlab-ci.yml file with following content:
+Create a .gitlab-ci.yml file with the following content:
 
 ```yml
 stages:
@@ -84,7 +84,7 @@ In addition, you can ensure that older deployment jobs are cancelled automatical
 
 ### Deploy secrets
 
-Is not recommended committing secrets in the repository, you could use a GitLab variable to store them.
+It is not recommended to commit secrets to the repository, you could use a GitLab variable to store them instead.
 
 Many frameworks use dotenv to store secrets, let's create a GitLab file variable named `DOTENV`, so it can be deployed along with the code.
 

docs/cli.md

@@ -1,19 +1,19 @@
 # CLI Usage
 
-We recommend adding next alias to your .bashrc file:
+We recommend adding the following alias to your .bashrc file:
 
 ```bash
 alias dep='vendor/bin/dep'
 ```
 
-As well as installing completion script for Deployer, completion supports:
+It is also recommended to install the completion script for Deployer. Completion supports:
 
 - tasks,
 - options,
 - host names,
 - and configs.
 
-For example for macOS run next commands:
+For example, on macOS run the following commands:
 
 ```bash
 brew install bash-completion
@@ -50,7 +50,8 @@ dep run 'uptime -p'
 
 ## Tree command
 
-Deployer has group tasks and before/after hooks, so see task tree use **dep tree** command:
+Deployer supports [task grouping](tasks.md#task-grouping) and [before/after hooks](tasks.md#addbefore). 
+To visualize the task hierarchy, use the **dep tree** command.
 
 ```
 $ dep tree deploy
@@ -80,8 +81,8 @@ The task-tree for deploy:
 
 ## Execution plan
 
-Before executing tasks, Deployer needs to flatten task tree and to decide in which order it will be executing tasks
-on which hosts. Use `--plan` option to output table with tasks/hosts:
+Before executing tasks, Deployer needs to flatten the task tree and decide in which order it will be executing tasks
+on which hosts. Use the `--plan` option to output a table with tasks/hosts:
 
 ```
 $ dep deploy --plan all
@@ -121,14 +122,14 @@ task('deploy:symlink')->limit(1);
 
 ## The `runLocally` working dir
 
-By default `runLocally()` commands are executed relative to the recipe file directory.
+By default, `runLocally()` commands are executed relative to the recipe file directory.
 This can be overridden globally by setting an environment variable:
 
 ```
 DEPLOYER_ROOT=. dep taskname`
 ```
 
-Alternatively the root directory can be overridden per command via the cwd configuration.
+Alternatively, the root directory can be overridden per command via the cwd configuration.
 
 ```php
 runLocally('ls', ['cwd' => '/root/directory']);

docs/getting-started.md

@@ -2,18 +2,18 @@
 
 In this tutorial we will cover:
 
-- Setting up a new host with provision recipe.
+- Setting up a new host with the [provision](recipe/provision.md) recipe.
 - Configuring a deployment and perfoming our first deploy.
 
-First, [install the Deployer](installation.md):
+First, [install Deployer](installation.md):
 
 Now lets cd into the project and run the following command:
 
 ```sh
 dep init
 ```
 
-Deployer will ask you a few question and after finishing you will have a
+Deployer will ask you a few questions, and after finishing you will have a
 **deploy.php** or **deploy.yaml** file. This is our deployment recipe.
 It contains hosts, tasks and requires other recipes. All framework recipes
 that come with Deployer are based on the [common](recipe/common.md) recipe.
@@ -27,18 +27,18 @@ If you already have a configured webserver you may skip to
 
 Let's create a new VPS on Linode, DigitalOcean, Vultr, AWS, GCP, etc.
 
-Make sure the image is **Ubuntu 20.04 LTS** as this version is supported via
-Deployer [provision](recipe/provision.md) recipe.
+Make sure the image is **Ubuntu 20.04 LTS** as this version is supported by
+Deployer's [provision](recipe/provision.md) recipe.
 
 :::tip
 Configure Reverse DNS or RDNS on your server. This will allow you to ssh into
-server using the domain name instead of the IP address.
+the server using the domain name instead of the IP address.
 :::
 
-Our **deploy.php** recipe contains a host definition with few important params:
+Our **deploy.php** recipe contains a host definition with a few important params:
 
-- `remote_user` user's name for ssh connection,
-- `deploy_path` host's path where we are going to deploy.
+- `remote_user` the user name for the ssh connection,
+- `deploy_path` the file path on the host where we are going to deploy.
 
 Let's set `remote_user` to be `deployer`. Right now our new server probably only has the `root` user. The provision recipe will 
 create and configure a `deployer` user for us.
@@ -58,8 +58,8 @@ Host *
   IdentityFile ~/.ssh/id_rsa
 ```
 
-Now let's provision our server. As our host doesn't have user `deployer`,
-we are going to override `remote_user` for provision via `-o remote_user=root`.
+Now let's provision our server. As our host doesn't have a user `deployer`,
+we are going to override `remote_user` for provisioning via `-o remote_user=root`.
 
 ```sh
 dep provision -o remote_user=root
@@ -76,8 +76,8 @@ dep provision -o become=root
 :::
 
 Deployer will ask you a few questions during provisioning: php version,
-database type, etc. Next Deployer will configure our server and create
-the `deployer` user. Provision takes around **5 minutes** and will install
+database type, etc. Next, Deployer will configure our server and create
+the `deployer` user. Provisioning takes around **5 minutes** and will install
 everything we need to run a website. A new website will be configured
 at [deploy_path](recipe/common.md#deploy_path).
 
@@ -92,16 +92,16 @@ dep deploy
 ```
 
 If deploy failed, Deployer will print an error message and which command was unsuccessful.
-Most likely we need to configure the correct database credentials in _.env_ file or similar.
+Most likely we need to configure the correct database credentials in the _.env_ file or similar.
 
-Ssh to the host, for example, for editing _.env_ file:
+Ssh to the host, for example, for editing the _.env_ file:
 
 ```sh
 dep ssh
 ```
 
 :::tip
-If your webserver is using OpenSSH version older than v7.6, updating the code may fail with the error
+If your webserver is using an OpenSSH version older than v7.6, updating the code may fail with the error
 message `unsupported option "accept-new".` In this case, override the Git SSH command with:
 ```php
 set('git_ssh_command', 'ssh');
@@ -140,7 +140,7 @@ location / {
 }
 ```
 
-If you're using provision recipe, Deployer will automatically configure the Caddy
+If you're using the [provision recipe](recipe/provision.md), Deployer will automatically configure the Caddy
 webserver to serve from the [public_path](/docs/recipe/provision/website.md#public_path).
 
 Now let's add a build step on our host:
@@ -168,5 +168,6 @@ task releases
 ```
 
 :::tip
-During development, the [dep push](recipe/deploy/push.md) task maybe useful.
+During development, the [dep push](recipe/deploy/push.md) task maybe useful
+to create a patch of local changes and push them to the host.
 :::

docs/hosts.md

@@ -85,9 +85,10 @@ Port of remote ssh server to connect to. Default is `22`.
 Default is `~/.ssh/config`.
 
 :::info Config file
-It is a good practice to keep connection parameters out of `deploy.php` file, as
-they can change depending on where the deploy is executed from. Only specify
-`hostname` and `remote_user` and other keep in `~/.ssh/config`:
+For best practices, avoid storing connection parameters in the `deploy.php file`, as 
+these can vary based on the deployment execution location. Instead, only include the 
+hostname and remote_user in `deploy.php`, while maintaining other parameters in the
+`~/.ssh/config` file.
 
 ```
 Host *