Update docs

Author: antonmedv

docs/installation.md

@@ -1,57 +1,125 @@
 # Installation
 
-## Global installation
+There are two ways to install Deployer: globally or locally. Global installation is recommended for most users, as it
+allows you to use Deployer from any directory.
+Local (or project) installation is preferred for CI/CD pipelines, as it allows you to use the same version of Deployer
+across all environments.
 
-To install Deployer, run next command in your project dir:
+## Global Installation
 
-```
+To install Deployer globally, use one of the following commands in your project directory:
+
+```sh
 composer global require deployer/deployer
 ```
 
-```
+Or:
+
+```sh
 phive install deployer
 ```
 
-Run in your project to create `deploy.php` file:
+:::tip Path to Executable
+
+Make sure that Composer's global bin directory is in your `PATH`. Typically, you can add the following line to your
+shell configuration file (e.g., `.bashrc`, `.zshrc`):
+
+```sh
+export PATH="$HOME/.composer/vendor/bin:$PATH"
 
-```
-dep init
 ```
 
-:::tip Autocomplete
+After adding this line, reload your shell configuration:
 
-Deployer comes with autocomplete support for task names, options, and hosts.
+```sh
+source ~/.bashrc
+```
 
-Run the next command to add bash completion support:
+or, for Zsh:
 
+```sh
+source ~/.zshrc
 ```
-dep completion bash > /etc/bash_completion.d/deployer
+
+:::
+
+To set up Deployer in your project and create the `deploy.php` configuration file, run:
+
+```sh
+dep init
 ```
 
-Make sure what your _.bashrc_ file includes generated file in some way.
+### Autocomplete Support
 
-:::
+Deployer includes support for autocompletion, helping you quickly find task names, options, and hosts. To enable
+autocomplete for various shells, use the following commands:
 
-## Project installation
 
-To install Deployer in your project, run next command in your project dir:
+- **Bash**:
 
-```
+  ```sh
+  dep completion bash > /etc/bash_completion.d/deployer
+  ```
+
+  Make sure your `.bashrc` file sources the generated file so that bash completion works.
+
+- **Zsh**:
+
+  ```sh
+  dep completion zsh > ~/.zsh/completion/_deployer
+  ```
+
+  Ensure that your `.zshrc` file includes the directory where `_deployer` is located in the `fpath`.
+
+- **Fish**:
+
+  ```sh
+  dep completion fish > ~/.config/fish/completions/deployer.fish
+  ```
+
+  The generated file will be automatically loaded by Fish.
+
+## Project Installation
+
+The project installation method is recommended for CI/CD pipelines, as it allows you to use the same version of Deployer
+across all environments.
+
+To install Deployer in your project, run the following command:
+
+```sh
 composer require --dev deployer/deployer
 ```
 
-To initialize deployer in your project run:
+:::tip Configuring Shell Alias
+To make using Deployer more convenient, you can set up a shell alias. This will allow you to run Deployer commands more
+easily. Add the following line to your shell configuration file (e.g., `.bashrc`, `.zshrc`):
 
+```sh
+alias dep='vendor/bin/dep'
 ```
+
+This alias lets you use `dep` instead of typing the full path each time.
+:::
+
+Then, to initialize Deployer in your project, use:
+
+```sh
 vendor/bin/dep init
 ```
 
-## Phar download
+## Downloading the Phar File
 
-You can download deployer phar file from [releases](https://github.com/deployphp/deployer/releases) page.
+Another option for installing Deployer is to download the Phar file. You can find the latest version on
+the [download page](/download).
 
-After downloading, you can run it in your project dir:
+Adding `deployer.phar` to your project repository is recommended to ensure everyone, including your CI pipeline, uses
+the same version of Deployer. This helps maintain consistency across all environments.
 
-```
+Once downloaded, run it in your project directory:
+
+```sh
 php deployer.phar init
 ```
+
+This method provides a simple way to use Deployer without needing Composer.
+