diff --git a/common.docs/i-bem-js/i-bem-js-common.ru.md b/common.docs/i-bem-js/i-bem-js-common.ru.md
index 9f2b8cc3..15e8f1cb 100644
--- a/common.docs/i-bem-js/i-bem-js-common.ru.md
+++ b/common.docs/i-bem-js/i-bem-js-common.ru.md
@@ -1,86 +1,217 @@
-## Общие сведения
+## Знакомьтесь: i-bem.js
 
-### БЭМ-методология и JavaScript
+* [Введение в компонентный подход](#Введение-в-компонентный-подход)
+* [Виртуальная DOM](#Виртуальная-dom)
+* [Настройка страницы](#Настройка-страницы)
+* [Модульная система i-bem.js](#Модульная-система-i-bemjs)
+* [Простой компонент](#Простой-компонент)
+* [Несколько компонентов](#Несколько-компонентов)
 
-В БЭМ-методологии веб-интерфейс строится из независимых **блоков** у которых могут быть **элементы**. И блоки, и элементы могут иметь состояния или особенности, описываемые **модификаторами**.
+### Введение в компонентный подход
 
-Работа веб-интерфейса обеспечивается несколькими **технологиями** (HTML, CSS, JS и т.д.). Его реализация разбита на компоненты по блокам. Блок содержит набор **файлов технологий**, составляющих аспекты его реализации:
 
-* `my-block.css` — внешний вид блока;
-* `my-block.bemhtml` — шаблоны для генерации HTML-представления блока;
-* `my-block.js` — **динамическое поведение** блока в браузере.
+### Виртуальная DOM
 
-Фреймворк `i-bem.js` позволяет разложить клиентский JavaScript на компоненты в терминах БЭМ:
+HTML — это набор инструкций, на основе которых браузер строит DOM. Когда браузер загружает код HTML, его элементы становятся элементами DOM.
 
-* **Блок** — JS-компонент, описывающий логику работы однотипных элементов интерфейса. Например, все кнопки могут быть реализованы в виде блока `button`. В этом случае, `button.css` определяет внешний вид всех кнопок, а `button.js` — логику их работы. На каждой странице может размещаться более одного **экземпляра блока** (например, кнопки). Каждому экземпляру блока соответствует JS-объект, в памяти браузера, хранящий его состояние. JS-объект содержит ссылку на DOM-узел, к которому привязан данный экземпляр блока.
-* **Элементы** — DOM-узлы, вложенные в DOM-узел блока, с атрибутом `class`, указывающим на их роль в БЭМ-предметной области (имя блока и элемента). Элементы блока доступны через [JS-API](./i-bem-js-states.ru.md#Управление-модификаторами) экземпляра блока.
-* **Модификаторы** — предоставляют информацию о состоянии блока и его элементов. Состояние модификаторов записывается в атрибуте `class` на DOM-узлах блока и элементов. Управление модификаторами производится через [JS-API](./i-bem-js-states.ru.md#Управление-модификаторами) экземпляра блока.
+HTML-элементы связаны друг с другом в иерархии: существуют родительские и дочерние элементы. Последнии, в свою очередь, могут быть родительскими для других элементов.
 
-### Сборка
+С появлением Ajax добавление новых HTML-элементов на страницу с небольшими порциями данных стало обычным делом. Изначально браузер загружает один HTML-документ. В ходе взаимодействия пользователя со страницей, JavaScript выполняет работу по разбору DOM и добавлению новых элементов интерфейса.
 
-Разработка в рамках БЭМ-методологии ведется модульно — каждый блок программируется отдельно. Финальный исходный код веб-страниц формируется из кода отдельных блоков с помощью процедур **сборки**.
+Управление изменениями DOM с помощью JavaScript может стать очень сложным и затратным по времени. Часто такое управление выполняется императивно:
 
-В файловой системе блок удобно представлять в виде каталога, а реализацию блока в каждой из технологий — в виде отдельного файла:
-
-```html
-    desktop.blocks/
-        my-block/
-            my-block.css
-            my-block.js
-            my-block.bemhtml
-            ...
-
-    desktop.blocks/
-        other-block/
-            other-block.css
-            other-block.js
-            other-block.bemhtml
-            ...
+```js
+const h1 = document.createElement("h1");
+h1.innerHTML = 'Hello, world!';
+document.body.appendChild(h1);
 ```
 
-Для каждой веб-страницы код использованных на ней блоков может быть собран в единые файлы:
+`i-bem.js` помогает работать с DOM декларативно и не думать о том, как найти тот или иной элемент. Все HTML-элементы объявленные в `i-bem.js` имеют свой JavaScript объект с набором инструкций, применяемых для построения пользовательского интерфейса и взаимодействия с браузером. Таким образом, разработчик изменяет виртуальную модель DOM, а `i-bem.js` отображает эти изменения наиболее эффективным образом.
 
-```html
-    desktop.bundles/
-        index/
-            index.html
-            index.css
-            index.js
-            ...
+### Настройка страницы
+
+Фреймворк `i-bem.js` входит в состав библиотеки [bem-core](https://ru.bem.info/platform/libs/bem-core/). Чтобы работать с `i-bem.js` в браузере, нужно подключить библиотеку на страницу. В примере ниже показано, как добавляется сценарий на страницу из Yаndex CDN.
+
+```diff index.html
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>Подключение i-bem.js</title>
+</head>
+<!-- Блок page -->
+<body class="page">
+
+    <!-- Библиотека bem-core -->
++   <script src="https://yastatic.net/bem-core/latest/desktop/bem-core.no-autoinit.js"></script>
+    <script>
+        // Код i-bem.js и JavaScript
+    </script>
+
+</body>
+</html>
 ```
 
-Существует два инструмента, поддерживающих БЭМ-предметную область, для сборки кода результирующих веб-страниц из отдельных описаний блоков:
+Это минимальные требования для работы с `i-bem.js` в браузере. Можно поместить ваш код JavaScript в отдельный файл, но он должен загружаться на страницу после загрузки `bem-core`.
+
+### Модульная система i-bem.js
+
+Модуль в `i-bem.js` представляет собой фрагмент кода, пригодный для многократного использования, который можно легко включить в другой модуль.
+
+`i-bem.js` использует модульную систему [ym/modules](https://github.com/ymaps/modules), которая позволяет:
+
+* Предоставлять модули асинхронно (`provide`).
+* Подключать модули асинхронно (`require`).
+* Переопределять и доопределять модули.
 
-* [bem-tools](https://ru.bem.info/toolbox/bem-tools/)
-* [ENB](https://ru.bem.info/toolbox/enb/)
+`i-bem.js` состоит из двух основных модулей:
 
-Оба инструмента позволяют автоматизировать создание HTML-разметки для [привязки JS-блоков](./i-bem-js-html-binding.ru.md#Привязка-js-блоков-к-html) и [передачи параметров экземпляру блока](./i-bem-js-params.ru.md#Передача-параметров-экземпляру-блока-и-элемента).
+* **i-bem**.
 
-### Почему i-bem.js так называется
+  JavaScript реализация блока `i-bem`. Модуль рассчитан на использование в любом JS-окружении: как на клиенте, так и на сервере (например, в Node.js).
 
-В соответствии с БЭМ-методологией, базовая JS-библиотека БЭМ-платформы изначально разрабатывалась как особый служебный блок. Такой подход позволяет работать с базовыми библиотеками так же, как и с обычными блоками. В частности, структурировать код в терминах элементов и модификаторов и гибко настраивать поведение библиотеки на разных уровнях переопределения.
+  Для декларации HTML-элемента в модуле `i-bem`, необходимо применить метод `bem.declBlock()`:
 
-Служебным блокам в БЭМ было принято давать имена с префиксом `i-`. Таким образом, имя `i-bem.js` читается как *реализация блока `i-bem` в технологии `JS`*.
+  ```js
+  modules.define('page', ['i-bem'], function(provide, bem){
+      // Декларируем блок page в модуле i-bem
+      provide(bem.declBlock(this.name, {
 
-### Как использовать i-bem.js
+      }));
+  });
+  ```
 
-Фреймворк `i-bem.js` входит в состав библиотеки [bem-core](https://ru.bem.info/platform/libs/bem-core/).
+* **i-bem-dom**.
 
-Реализация `i-bem.js` состоит из двух модулей:
+  [Виртуальная DOM](#Виртуальная-dom) (JavaScript реализация DOM). Модуль рассчитан на использование на клиенте.
 
-* **Модуль [i-bem](https://ru.bem.info/platform/libs/bem-core/)**.
+  Для декларации HTML-элемента в модуле `i-bem-dom`, необходимо применить метод `bemDom.declBlock()`:
 
-  Предоставляет базовую реализацию JS-блока `i-bem`, от которой наследуются все блоки и элементы в `i-bem.js`. Блок `i-bem` написан с расчетом на использование в любом JS-окружении: как на клиенте, так и на сервере (например, в Node.js).
+  ```js
+  modules.define('page', ['i-bem-dom'], function(provide, bemDom){
+       // Декларируем блок page в модуле i-bem-dom
+      provide(bemDom.declBlock(this.name, {
 
-* **Модуль [i-bem-dom](https://ru.bem.info/platform/libs/bem-core/)**.
+      }));
+  });
+  ```
+  > **Примечание.** Зависит от библиотеки [jQuery](https://jquery.com), поэтому отдельная установка не требуется. Все методы jQuery доступны по умолчанию.
 
-  Предоставляет базовую реализацию блока и элемента, привязанных к DOM-узлу. Рассчитан на использование на клиенте, опирается на работу браузеров с DOM. Зависит от `jQuery`.
+### Простой компонент
 
-Зависимости:
+Для Задекларируем блок `page` в виртуальной DOM, после чего вызовем метод  `bemDom.prepend()` для создания нового HTML-элемента.
 
-* jQuery (только для модуля `i-bem-dom`). При использовании `bem-core` отдельная установка jQuery не требуется.
-* Модульная система [ym/modules](https://github.com/ymaps/modules). При использовании [ENB](https://ru.bem.info/toolbox/enb/) с технологией `.browser.js` (и производных от нее) эта зависимость удовлетворяется автоматически.
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>Простой компонент</title>
+</head>
+<!-- Блок page -->
+<body class="page i-bem" data-bem='{ "page": {} }'>
+
+    <!-- Библиотека bem-core -->
+    <script src="https://yastatic.net/bem-core/latest/desktop/bem-core.no-autoinit.js"></script>
+    <script>
+    modules.define('page', ['i-bem-dom'], function(provide, bemDom){
+        provide(bemDom.declBlock(this.name, {
+            onSetMod: {
+                js: {
+                    inited: function() {
+                        bemDom.prepend(this.domElem, '<h1 class="heading">Hello, world!</h1>');
+                    }
+                }
+            },
+
+        }));
+    });
+    // Инициализация
+    modules.require('i-bem-dom__init', function(init) { init(); });
+    </script>
+
+</body>
+</html>
+```
+
+### Несколько компонентов
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>Несколько компонентов</title>
+</head>
+<!-- Блок page -->
+<body class="page i-bem" data-bem='{ "page": {} }'>
+    <!-- Блок user -->
+    <div class="user i-bem" data-bem='{ "user": {} }'></div>
+
+    <!-- Библиотека bem-core -->
+    <script src="https://yastatic.net/bem-core/latest/desktop/bem-core.no-autoinit.js"></script>
+    <script>
+    // Модуль блока page
+    modules.define('page', ['i-bem-dom'], function(provide, bemDom){
+        provide(bemDom.declBlock(this.name, {
+            onSetMod: {
+                js: {
+                    inited: function() {
+                        bemDom.prepend(this.domElem, '<h1 class="heading">Hello, world!</h1>');
+                    }
+                }
+            }
+        }));
+    });
+    // Модуль блока user
+    modules.define('user', ['i-bem-dom'], function(provide, bemDom){
+        provide(bemDom.declBlock(this.name, {
+            onSetMod: {
+                js: {
+                    inited: function() {
+                        const user = 'Ben Reilly';
+                        bemDom.prepend(this.domElem, '<h2 class="heading">Hello, '+ user +'!</h2>');
+                    }
+                }
+            }
+        }));
+    });
+    // Инициализация
+    modules.require('i-bem-dom__init', function(init) { init(); });
+    </script>
+
+</body>
+</html>
+```
+
+JavaScript-реализацию каждого блока можно вынести в отдельные файлы и затем выполнить инициализацию модуля `i-bem-dom`:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>Несколько компонентов</title>
+</head>
+<!-- Блок page -->
+<body class="page i-bem" data-bem='{ "page": {} }'>
+    <!-- Блок user -->
+    <div class="user i-bem" data-bem='{ "user": {} }'></div>
+
+    <!-- Библиотека bem-core -->
+    <script src="https://yastatic.net/bem-core/latest/desktop/bem-core.no-autoinit.js"></script>
+    <script src="page.js"></script>
+    <script src="user.js"></script>
+    <script>
+    // Инициализация
+    modules.require('i-bem-dom__init', function(init) { init(); });
+    </script>
+
+</body>
+</html>
+```
 
-Можно использовать `i-bem.js` как часть полного стека БЭМ-инструментов. В этом случае свой проект удобно создавать на основе шаблонного репозитория [project-stub](https://ru.bem.info/platform/project-stub/), в котором настроена автоматическая установка зависимых библиотек и сборка.
+Чаще все JavaScript-реализации блоков [собирают в отдельный бандл](https://ru.bem.info/methodology/build/), который подключают на страницу. Тема сборки выходят за рамки этого документа, поэтому вы можете использовать готовые шаблонные репозитории, где сборка бандлов настроена по умолчанию:
 
-Если не планируется использование других технологий БЭМ-платформы, достаточно поместить код библиотеки `bem-core` в существующий проект.
+* [project-stub](https://github.com/bem/project-stub) — для статических проектов;
+* [bem-express](https://github.com/bem/bem-express) — для динамических проектов.
diff --git a/common.docs/i-bem-js/i-bem-js-extras.en.md b/common.docs/i-bem-js/i-bem-js-extras.en.md
deleted file mode 100644
index bd214c84..00000000
--- a/common.docs/i-bem-js/i-bem-js-extras.en.md
+++ /dev/null
@@ -1,14 +0,0 @@
-## What next?
-
-For information about the BEM methodology, tools, and news in the BEM world, visit the website [bem.info](https://en.bem.info/).
-
-For complete information about all the `i-bem.js` API methods, see the section [JSDoc](https://en.bem.info/libs/bem-core/current/desktop/i-bem/jsdoc/) for the `i-bem` block.
-
-To share your experience with BEM or submit questions for experienced users and `i-bem.js` developers, visit the [forum](https://en.bem.info/forum/).
-
-For `i-bem.js` usage examples and additional information, see these articles:
-
-* [JavaScript for BEM: main terms](https://en.bem.info/articles/bem-js-main-terms/)
-* [i-bem.js tutorial](https://en.bem.info/tutorials/bem-js-tutorial/)
-* [Starting your own BEM project](https://en.bem.info/tutorials/start-with-project-stub/)
-* [Creating BEM application on Leaflet and 2GIS API](https://en.bem.info/articles/firm-card-story/)
diff --git a/common.docs/i-bem-js/i-bem-js-extras.ru.md b/common.docs/i-bem-js/i-bem-js-extras.ru.md
deleted file mode 100644
index a0eac176..00000000
--- a/common.docs/i-bem-js/i-bem-js-extras.ru.md
+++ /dev/null
@@ -1,14 +0,0 @@
-## Что дальше?
-
-Информацию о БЭМ-методологии, инструментарии и новостях в мире БЭМ смотрите на сайте [bem.info](https://ru.bem.info).
-
-Полную информацию обо всех методах API `i-bem.js` можно найти в разделе JSDoc [блока i-bem](https://ru.bem.info/platform/i-bem/) и [i-bem-dom](https://ru.bem.info/platform/i-bem/).
-
-Обменяться опытом и задать вопрос опытным пользователям и разработчикам `i-bem.js` можно на [форуме](https://ru.bem.info/forum/).
-
-Примеры использования `i-bem.js` и дополнительную информацию смотрите в статьях:
-
-* [JavaScript по БЭМ: основные понятия](https://ru.bem.info/articles/bem-js-main-terms/)
-* [Справочное руководство по i-bem.js](https://ru.bem.info/platform/tutorials/i-bem/)
-* [Создаем свой проект на БЭМ](https://ru.bem.info/platform/tutorials/start-with-project-stub/)
-* [БЭМ-приложение на Leaflet и API 2GIS](https://ru.bem.info/articles/firm-card-story/)
diff --git a/common.docs/i-bem-js/i-bem-js.ru.md b/common.docs/i-bem-js/i-bem-js.ru.md
index df603ef4..f6c33a15 100644
--- a/common.docs/i-bem-js/i-bem-js.ru.md
+++ b/common.docs/i-bem-js/i-bem-js.ru.md
@@ -1,21 +1,31 @@
-# i-bem.js: руководство пользователя
+# i-bem.js
 
-## i-bem.js: JavaScript-фреймворк для БЭМ
+* [Введение](#Введение)
+* [Структура документа](#Структура-документа)
+* [См. также](#См-также)
 
-`i-bem.js` — специализированный JavaScript-фреймворк для веб-разработки в рамках [БЭМ-методологии](https://ru.bem.info/methodology/).
+## Введение
 
-`i-bem.js` позволяет:
+`i-bem.js` — JavaScript-фреймворк для разработки пользовательских интерфейсов. Он был создан в [Яндексе](https://www.yandex.ru) с целью решить ряд проблем, связанных с крупномасштабными сайтами.
 
-* разрабатывать веб-интерфейс в терминах блоков, элементов, модификаторов;
-* описывать логику работы блока в декларативном стиле — как набор состояний;
-* легко интегрировать JavaScript-код с BEMHTML- или BH-шаблонами и CSS в стиле БЭМ;
-* гибко переопределять поведение библиотечных блоков.
+Позволяет:
+
+* разрабатывать интерфейс независимыми блоками;
+* описывать логику работы блоков в декларативном стиле;
+* легко интегрировать JavaScript-код с BEMHTML- или BH-шаблонами и CSS в DOM (объектную модель документа);
+* гибко переопределять поведение блоков.
+
+> **Примечание.** `i-bem.js` не предназначен для замены фреймворка общего назначения, подобного jQuery.
+
+## Структура документа
+
+* [Знакомьтесь: i-bem.js](./i-bem-js-common.ru.md)
+
+
+* ======
 
-`i-bem.js` не предназначен для замены фреймворка общего назначения, подобного jQuery.
 
-**Краткий обзор содержания документа**:
 
-* [Общие сведения](./i-bem-js-common.ru.md) о фреймворке: связь с предметной областью БЭМ, краткое описание модульной структуры фреймворка, шаблонного проекта и инструментов для сборки кода, написанного с использованием `i-bem.js`.
 * [Привязка JS-экземпляров к HTML](./i-bem-js-html-binding.ru.md) — разметка JS-блоков в HTML-коде страницы, варианты соотношения HTML-элементов и JS-экземпляров.
 * [Декларация](./i-bem-js-decl.ru.md) — синтаксис описания класса блока и элемента.
 * [Передача параметров](./i-bem-js-params.ru.md) — передача параметров экземпляру блока и элемента, получение доступа к параметрам из экземпляра.
@@ -26,4 +36,9 @@
 * [Инициализация](./i-bem-js-init.ru.md) — инициализация экземпляров блоков и элементов.
 * [Взаимодействие блоков](./i-bem-js-interact.ru.md) — обращение из экземпляра блока или элемента к другим экземплярам и классам.
 * [Контекст](./i-bem-js-context.ru.md) —  собственные и статические свойства блока и элемента. Статические свойства `i-bem-dom`.
-* [Что дальше?](./i-bem-js-extras.ru.md) — ссылки на документацию и дополнительные материалы.
+
+
+## См. также
+
+* [Справочное руководство по i-bem.js](https://ru.bem.info/platform/tutorials/i-bem/)
+* [Учебные материалы](https://ru.bem.info/platform/tutorials/)