docs(usage): small improvements (#5617)

docs/pages_en/usage/build/images.md

@@ -368,7 +368,7 @@ During the build, werf will automatically insert the appropriate names and ident
 
 ## Multi-platform and cross-platform building
 
-werf can build images for either the native host platform where werf have started, or for arbitrary platform in cross-platform mode using emulation. Also it is possible to build images for multiple platforms at the same time (i.e. manifest-list images).
+werf can build images for either the native host platform in which it is running, or for arbitrary platform in cross-platform mode using emulation. It is also possible to build images for multiple target platforms at once (i.e. manifest-list images).
 
 > **NOTE:** Refer to the [Installation]({{ "index.html" | true_relative_url }}) for more information about preparing host system for cross-platform builds, and [Build process]({{ "/usage/build/process.html" | true_relative_url }}) for more information on multi-platform support for different syntaxes and backends.
 

docs/pages_en/usage/build/overview.md

@@ -8,6 +8,7 @@ Delivering an application to Kubernetes involves containerizing it (building one
 The build process is as follows: the user specifies the build instructions in the form of a Dockerfile or an alternative Stapel build syntax, and werf takes care of:
 
 * orchestration of simultaneous/parallel building of application images;
+* cross-platform and multi-platform image building;
 * shared cache for intermediate layers and images in the container registry which is accessible from any runners;
 * optimal tagging scheme based on image content which prevents unnecessary rebuilds and application waiting time during deployment;
 * system of reproducibility and immutability of images for a commit: the images once built for a commit won't be re-built.

docs/pages_en/usage/build/process.md

@@ -264,7 +264,7 @@ The synchronization server can be run with the `werf synchronization` command. I
 werf synchronization --host 0.0.0.0 --port 55581
 ```
 
-— This server only supports HTTP mode, to use HTTP, you have to configure additional SSL termination by third-party tools (e.g., via the Kubernetes Ingress).
+— This server only supports HTTP mode. To use HTTPS, you have to configure additional SSL termination by third-party tools (e.g., via the Kubernetes Ingress).
 
 Then, for all werf commands that use the `--repo` parameter, the `--synchronization=http[s]://DOMAIN` parameter must be specified as well, for example:
 
@@ -304,11 +304,11 @@ werf converge --repo registry.mydomain.org/repo --synchronization :local
 
 > **NOTE:** This method is only suitable if all werf runs are triggered by the same runner in your CI/CD system.
 
-## Multiplatform builds
+## Multi-platform builds
 
-Multiplatform builds use the cross-platform instruction execution mechanics provided by the [Linux kernel](https://en.wikipedia.org/wiki/Binfmt_misc) and the QEMU emulator. [List of supported architectures](https://www.qemu.org/docs/master/about/emulation.html). Refer to the [Installation]({{ "index.html" | true_relative_url }}) for more information about preparing host system for cross-platform builds.
+Multi-platform builds use the cross-platform instruction execution mechanics provided by the [Linux kernel](https://en.wikipedia.org/wiki/Binfmt_misc) and the QEMU emulator. [List of supported architectures](https://www.qemu.org/docs/master/about/emulation.html). Refer to the [Installation]({{ "index.html" | true_relative_url }}) section for more information on how to configure the host system to do cross-platform builds.
 
-The table below summarizes support of multiplatform building for different configuration syntaxes, building modes, and build backends:
+The table below summarizes support of multi-platform building for different configuration syntaxes, building modes, and build backends:
 
 |                         | buildah        | docker-server      |
 |---                      |---             |---                 |

docs/pages_en/usage/deploy/overview.md

@@ -7,10 +7,13 @@ When setting up application delivery in Kubernetes, you must decide which format
 
 Helm is built into werf and is used for these tasks. Configuration development and maintenance is carried out using Helm charts. As for the deployment process, Helm in werf provides some advanced features:
 
-- smart resource state tracking during deployment;
-- specifying the deployment order for any resources, not just hooks;
-- waiting for non-release resources to be created and ready;
-- integration of the assembly and deployment and other features.
+- tracking the status of deployed resources (with the option to change the behaviour [for each resource])({{ "/reference/deploy_annotations.html" | true_relative_url }})):
+  - smart waiting for resources to become ready;
+  - instant termination of a failed deployment without the need to wait for a timeout;
+  - deployment progress, logs, system events and application errors.
+- arbitrary deployment order for any resources, not just hooks;
+- waiting for resources that are not part of the release to be created and ready;
+- integrating building and deployment, and much more.
 
 werf strives to make working with Helm easier, more convenient and flexible without breaking backward compatibility with Helm charts, Helm templates, and Helm releases.
 

docs/pages_en/usage/deploy/releases.md

@@ -11,7 +11,7 @@ From a technical point of view, werf releases are Helm 3 releases and therefore
 
 ## Automatic release name generation (werf only)
 
-By default, the release name is generated automatically using a special pattern `[[ project ]]-[[ env ]]`, where `[ project ]]` is the werf project name and `[ env ]]` is the environment name, for example:
+By default, the release name is generated automatically using a special pattern `[[ project ]]-[[ env ]]`, where `project` is the werf project name and `env` is the environment name, for example:
 
 ```yaml
 # werf.yaml:
@@ -106,4 +106,4 @@ werf converge \
   --add-label "gitlab-user-email=vasya@myproject.com" \
   --env dev \
   --repo REPO
-```
+```

docs/pages_en/usage/deploy/tracking.md

@@ -5,7 +5,7 @@ permalink: usage/deploy/tracking.html
 
 ## Tracking resource status
 
-The resource deployment process consists of two steps: applying resources to the cluster and *tracking the state* of those resources. werf implements advanced resource state tracking (werf only) via the [kubedog] library (https://github.com/werf/kubedog).
+The resource deployment process consists of two steps: applying resources to the cluster and *tracking the state* of those resources. werf implements advanced resource state tracking (werf only) via the [kubedog](https://github.com/werf/kubedog) library.
 
 Resource tracking is enabled by default for all supported resource types, namely:
 
@@ -133,4 +133,4 @@ metadata:
   name: myapp
   annotations:
     werf.io/show-service-messages: "true"
-```
+```

docs/pages_ru/usage/build/overview.md

@@ -8,6 +8,7 @@ permalink: usage/build/overview.html
 Для сборки пользователю необходимо описать сборочные инструкции в виде Dockerfile'а или альтернативного сборочного синтаксиса stapel, а остальное werf возьмёт на себя:
 
 * оркестрация одновременной/параллельной сборки образов приложения;
+* кроссплатформенная и мультиплатформенная сборка образов;
 * общий кеш промежуточных слоёв и образов в container registry, доступный с любых раннеров;
 * оптимальная схема тегирования, основанная на содержимом образа, предотвращающая лишние пересборки и время простоя приложения при выкате;
 * система обеспечения воспроизводимости и неизменности образов для коммита: однажды собранные образы для коммита более не будут пересобраны.

docs/pages_ru/usage/deploy/overview.md

@@ -7,10 +7,13 @@ permalink: usage/deploy/overview.html
 
 В werf встроен Helm, и именно он используется для решения перечисленных задач. Разработка и сопровождение конфигурации реализуется с помощью Helm-чарта, а для процесса развёртывания предлагается Helm c дополнительными возможностями:
 
-- умным отслеживанием состояния ресурсов при развертывании;
-- использованием произвольного порядка развертывания для любых ресурсов, а не только для хуков;
-- ожиданием создания и готовности ресурсов, не принадлежащих релизу;
-- интеграцией сборки и развертывания и многим другим.
+- отслеживание состояния выкатываемых ресурсов (с возможностью изменения поведения [для каждого ресурса]({{ "/reference/deploy_annotations.html" | true_relative_url }})):
+  - умное ожидание готовности ресурсов;
+  - мгновенное завершение проблемного развертывания без необходимости ожидания таймаута;
+  - прогресс развёртывания, логи, системные события и ошибки приложения.
+- использование произвольного порядка развертывания для любых ресурсов, а не только для хуков;
+- ожидание создания и готовности ресурсов, не принадлежащих релизу;
+- интеграция сборки и развертывания и многое другое.
 
 werf стремится сделать работу с Helm более простой, удобной и гибкой, при этом не ломая обратную совместимость с Helm-чартами, Helm-шаблонами и Helm-релизами.
 

docs/pages_ru/usage/deploy/releases.md

@@ -11,7 +11,7 @@ permalink: usage/deploy/releases.html
 
 ## Автоматическое формирование имени релиза (только в werf)
 
-По умолчанию имя релиза формируется автоматически по специальному шаблону `[[ project ]]-[[ env ]]`, где `[[ project ]]` — имя проекта werf, а `[[ env ]]` — имя окружения, например:
+По умолчанию имя релиза формируется автоматически по специальному шаблону `[[ project ]]-[[ env ]]`, где `project` — имя проекта werf, а `env` — имя окружения, например:
 
 ```yaml
 # werf.yaml: