Update docs

Author: antonmedv

docs/basics.md

@@ -1,44 +1,44 @@
 # Basics
 
-Deployer has two main concepts: [**hosts**](hosts.md) and [**tasks**](tasks.md).
+Deployer operates around two main concepts: [**hosts**](hosts.md) and [**tasks**](tasks.md). These are defined within a
+**recipe**, which is simply a file containing **hosts** and **tasks** definitions.
 
-A **recipe** is a file containing definitions for **hosts** and **tasks**.
+The Deployer CLI requires two arguments:
 
-Deployer CLI requires two arguments to run: a **task** to run and a **selector**.
+1. A **task** to execute.
+2. A **selector** to determine the hosts the task will run on.
 
-Hosts can also be [selected via labels](hosts.md#labels), also a default host selection can be configured.
+Here's an example:
 
-```
+```sh
 $ dep deploy deployer.org
-  --- ------ ------------
-   |    |         |
-   |    |         `--- Selector
-   |    `------------- Task
-   `------------------ CLI
+      ------ ------------
+       task    selector
 ```
 
-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.
+Deployer uses the [selector](selector.md) to choose which hosts to execute the task on. After selecting hosts, it
+prepares the environment (details later) and runs the task.
 
-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`.
+### Host Selection
 
-The `dep` CLI looks for a `deploy.php` or `deploy.yaml` file in the current directory.
+- If no selector is specified, Deployer prompts you to choose a host.
+- If your recipe has only one host, it is automatically selected.
+- To run a task on all hosts, use the `all` selector.
 
-Or a recipe can be specified explicitly via `-f` or `--file` option.
+By default, the `dep` CLI looks for a `deploy.php` or `deploy.yaml` file in the current directory. Alternatively, you
+can specify a recipe file explicitly using the `-f` or `--file` option:
 
-```
+```sh
 $ dep --file=deploy.php deploy deployer.org
 ```
 
-Let's write a recipe.
+---
+
+## Writing Your First Recipe
+
+Here's an example of a simple recipe:
 
 ```php
-// 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;
 
 host('deployer.org');
@@ -48,57 +48,56 @@ task('my_task', function () {
 });
 ```
 
-Let's try to run our task on deployer.org.
+To execute this task on `deployer.org`:
 
-```
+```sh
 $ dep my_task
 task my_task
-$
 ```
 
-If no host is provided and no default_selector is set, Deployer will show an interactive prompt for selecting hosts.
-If your recipe contains only one host, Deployer will automatically choose it. 
-To select all hosts specify `all`.
-
-But where is our `whoami` command output? By default, Deployer runs with normal verbosity
-level and shows only the names of executed tasks. Let's increase verbosity to verbose, and
-rerun our task.
+### Increasing Verbosity
 
-Add `-v` option to increase verbosity. Read more about [CLI usage](cli.md).
+By default, Deployer only shows task names. To see detailed output (e.g., the result of the `whoami` command), use the
+`-v` option:
 
-```
+```sh
 $ dep my_task -v
 task my_task
 [deployer.org] run whoami
 [deployer.org] deployer
-$
 ```
 
-Now let's add a second host:
+---
+
+## Working with Multiple Hosts
+
+You can define multiple hosts in your recipe:
 
 ```php
 host('deployer.org');
 host('medv.io');
 ```
 
-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.
+Deployer connects to hosts using the same `~/.ssh/config` file as the `ssh` command. Alternatively, you can
+specify [connection options](hosts.md) directly in the recipe.
 
-Let's run `my_task` task on both hosts:
+Run a task on both hosts:
 
-```
+```sh
 $ dep my_task -v all
 task my_task
 [deployer.org] run whoami
 [medv.io] run whoami
-[medv.io] anton
 [deployer.org] deployer
+[medv.io] anton
 ```
 
-Deployer runs a task in parallel on each host. This is why the output is mixed.
-We can limit it to run only on one host at a time.
+### Controlling Parallelism
 
-```
+By default, tasks run in parallel on all selected hosts, which may mix the output. To limit execution to one host at a
+time:
+
+```sh
 $ dep my_task -v all --limit 1
 task my_task
 [deployer.org] run whoami
@@ -107,21 +106,20 @@ task my_task
 [medv.io] deployer
 ```
 
-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.
+You can also specify a [limit level](tasks.md#limit) for individual tasks to control parallelism.
+
+---
+
+## Configuring Hosts
 
-Each host has a configuration: a list of key-value pairs. Let's define our first
-configuration option for both our hosts:
+Each host can have a set of key-value configuration options. Here's an example:
 
 ```php
-host('deployer.org')
-    ->set('my_config', 'foo');
-host('medv.io')
-    ->set('my_config', 'bar');
+host('deployer.org')->set('my_config', 'foo');
+host('medv.io')->set('my_config', 'bar');
 ```
 
-In the task we can get the currently executing host using the [currentHost](api.md#currenthost) function:
+Access these options in a task using the [currentHost](api.md#currenthost) function:
 
 ```php
 task('my_task', function () {
@@ -130,41 +128,28 @@ task('my_task', function () {
 });
 ```
 
-Or with the [get](api.md#get) function:
+Or more concisely with the [get](api.md#get) function:
 
-```diff
+```php
 task('my_task', function () {
--   $myConfig = currentHost()->get('my_config');
-+   $myConfig = get('my_config');
+    $myConfig = get('my_config');
     writeln("my_config: " . $myConfig);
 });
 ```
 
-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 the **parse** function
-internally. So you don't need to call the **parse** function by yourself.
+Or using brackets syntax `{{` and `}}`:
 
-```diff
+```php
 task('my_task', function () {
--   $myConfig = get('my_config');
--   writeln("my_config: " . $myConfig);
-+   writeln("my_config: {{my_config}}");
+    writeln("my_config: {{my_config}}");
 });
 ```
 
-Let's try to run our task:
+---
 
-```
-$ dep my_task all
-task my_task
-[deployer.org] my_config: foo
-[medv.io] my_config: bar
-```
+## Global Configurations
 
-Awesome! Each host configuration inherits global configuration. Let's refactor
-our recipe to define one global config option:
+Host configurations inherit global options. Here's how to set a global configuration:
 
 ```php
 set('my_config', 'global');
@@ -173,11 +158,23 @@ host('deployer.org');
 host('medv.io');
 ```
 
-The config option `my_config` will be equal to `global` on both hosts.
+Both hosts will inherit `my_config` with the value `global`. You can override these values for individual hosts as
+needed.
+
+
+```php
+set('my_config', 'global');
+
+host('deployer.org');
+host('medv.io')->set('my_config', 'bar');
+```
+
+---
 
-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.
+## Dynamic Configurations
+
+You can define dynamic configuration values using callbacks. These are evaluated the first time they are accessed, and
+the result is stored for subsequent use:
 
 ```php
 set('whoami', function () {
@@ -189,22 +186,18 @@ task('my_task', function () {
 });
 ```
 
-Let's try to run it:
+When executed:
 
-```
+```sh
 $ dep my_task all
 task my_task
 [deployer.org] Who am I? deployer
 [medv.io] Who am I? anton
 ```
 
-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.
+---
 
-
-Here is an example:
+Dynamic configurations are cached after the first use:
 
 ```php
 set('current_date', function () {
@@ -218,10 +211,9 @@ task('my_task', function () {
 });
 ```
 
-If we run my_task, we will see that `date` is called only once on
-`{{current_date}}` access.
+Running this task:
 
-```
+```sh
 $ dep my_task deployer.org -v
 task my_task
 [deployer.org] run date
@@ -231,15 +223,23 @@ task my_task
 [deployer.org] What time is it? Wed 03 Nov 2021 01:16:53 PM UTC
 ```
 
-We can override a config option via CLI option `-o` like this:
+---
 
-```
+## Overriding Configurations via CLI
+
+You can override configuration values using the `-o` option:
+
+```sh
 $ dep my_task deployer.org -v -o current_date="I don't know"
 task my_task
 [deployer.org] What time is it? I don't know
 [deployer.org] run sleep 5
 [deployer.org] What time is it? I don't know
 ```
 
-Since the `current_date` config option is overridden there is no need to call the callback.
-So there is no 'run date'.
+Since `current_date` is overridden, the callback is never executed.
+
+---
+
+By now, you should have a solid understanding of Deployer’s basics, from defining tasks and hosts to working with
+configurations and dynamic values. Happy deploying!