diff --git a/README.md b/README.md
index 16e8734..911f8d1 100644
--- a/README.md
+++ b/README.md
@@ -42,268 +42,23 @@ This **open-source plugin was developed to help the Sylius community**. If you h
 [![](https://bitbag.io/wp-content/uploads/2020/10/button-contact.png)](https://bitbag.io/contact-us/?utm_source=github&utm_medium=referral&utm_campaign=plugins_blacklist)
 
 ## Installation
-```bash
-composer require bitbag/blacklist-plugin --no-scripts
-```
-
-Add plugin dependencies to your `config/bundles.php` file:
-```php
-return [
-    ...
-
-    BitBag\SyliusBlacklistPlugin\BitBagSyliusBlacklistPlugin::class => ['all' => true],
-];
-```
-
-Import required config in your `config/packages/_sylius.yaml` file:
-```yaml
-# config/packages/_sylius.yaml
-
-imports:
-    ...
-    
-    - { resource: "@BitBagSyliusBlacklistPlugin/Resources/config/config.yaml" }
-```
-
-Import routing in your `config/routes.yaml` file:
-
-```
-# config/routes.yaml
-
-bitbag_sylius_blacklist_plugin:
-    resource: "@BitBagSyliusBlacklistPlugin/Resources/config/routing.yaml"
-```
-
-Add traits to your Customer entity class, when You don't use annotation.
-
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Entity\Customer;
-
-use BitBag\SyliusBlacklistPlugin\Model\FraudStatusTrait;
-use Sylius\Component\Core\Model\Customer as BaseCustomer;
-
-class Customer extends BaseCustomer implements CustomerInterface
-{
-    use FraudStatusTrait;
-}
-```
-
-Define new Entity mapping inside your src/Resources/config/doctrine directory.
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-
-<doctrine-mapping
-    xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd"
->
-    <entity name="App\Entity\Customer\Customer" table="sylius_customer">
-        <field name="fraudStatus" column="fraud_status" type="string" />
-    </entity>
-</doctrine-mapping>
-```
-
-Or edit Customer Entity this way if you use attributes:
-
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Entity\Customer;
-
-use Doctrine\ORM\Mapping as ORM;
-use Sylius\Component\Core\Model\Customer as BaseCustomer;
-
-#[ORM\Entity]
-#[ORM\Table(name: 'sylius_customer')]
-class Customer extends BaseCustomer implements CustomerInterface
-{
-    #[ORM\Column(type: 'string', nullable: false)]
-    protected $fraudStatus = FraudStatusInterface::FRAUD_STATUS_NEUTRAL;
-
-    public function getFraudStatus(): ?string
-    {
-        return $this->fraudStatus;
-    }
-
-    public function setFraudStatus(?string $fraudStatus): void
-    {
-        $this->fraudStatus = $fraudStatus;
-    }
-}
-
-```
-
-Or edit Customer Entity this way if you use annotations:
-
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Entity\Customer;
-
-use Doctrine\ORM\Mapping as ORM;
-use Sylius\Component\Core\Model\Customer as BaseCustomer;
 
-/**
-* @ORM\Entity 
-* @ORM\Table(name="sylius_customer")
-*/
-class Customer extends BaseCustomer implements CustomerInterface
-{
-    /**
-     * @var string
-     * @ORM\Column(type="string", nullable=false)
-     */
-    protected $fraudStatus = FraudStatusInterface::FRAUD_STATUS_NEUTRAL;
-
-    public function getFraudStatus(): ?string
-    {
-        return $this->fraudStatus;
-    }
-
-    public function setFraudStatus(?string $fraudStatus): void
-    {
-        $this->fraudStatus = $fraudStatus;
-    }
-}
-```
-
-Create also interface, which is implemented by customer entity
-
-```php
-<?php
-
-namespace App\Entity\Customer;
-
-use BitBag\SyliusBlacklistPlugin\Entity\Customer\FraudStatusInterface;
-use Sylius\Component\Core\Model\CustomerInterface as BaseCustomerInterface;
-
-interface CustomerInterface extends BaseCustomerInterface, FraudStatusInterface
-{
-}
-```
-Override Customer resource:
-
-```yaml
-# config/packages/_sylius.yaml
-...
-
-sylius_customer:
-    resources:
-        customer:
-            classes:
-                model: App\Entity\Customer\Customer
-                repository: App\Repository\Customer\CustomerRepository
-```
-
-Create or edit `CustomerRepository.php` file:
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Repository\Customer;
-
-use BitBag\SyliusBlacklistPlugin\Repository\CustomerRepositoryTrait;
-use Sylius\Bundle\CoreBundle\Doctrine\ORM\CustomerRepository as BaseCustomerRepository;
-
-class CustomerRepository extends BaseCustomerRepository
-{
-    use CustomerRepositoryTrait;
-}
-```
-
-Override Customer grid:
-
-```yaml
-# config/packages/_sylius.yaml
-...
-
-sylius_grid:
-    grids:
-        sylius_admin_customer:
-            fields:
-                ...
-                fraudStatus:
-                    type: twig
-                    label: bitbag_sylius_blacklist_plugin.ui.fraud_status
-                    options:
-                        template: "@BitBagSyliusBlacklistPlugin/Customer/Grid/Field/fraudStatus.html.twig"
-            filters:
-                ...
-                fraudStatus:
-                    type: select
-                    label: bitbag_sylius_blacklist_plugin.ui.fraud_status
-                    form_options:
-                        choices:
-                            bitbag_sylius_blacklist_plugin.ui.neutral: Neutral
-                            bitbag_sylius_blacklist_plugin.ui.blacklisted: Blacklisted
-```
-
-```yaml
-# config/packages/twig.yaml
-...
-
-twig:
-  paths: ['%kernel.project_dir%/templates']
-  debug: '%kernel.debug%'
-  strict_variables: '%kernel.debug%'
-  form_themes:
-    - '@BitBagSyliusBlacklistPlugin/Form/theme.html.twig'
-    - '@SyliusUi/Form/theme.html.twig'
-services:
-  _defaults:
-    public: false
-    autowire: true
-    autoconfigure: true
-
-  Twig\Extra\Intl\IntlExtension: ~
-
-when@test_cached:
-  twig:
-    strict_variables: true
-
-```
-
-Override Customer form template (`@SyliusAdminBundle\Customer\_form.html.twig` or `@SyliusAdminBundle/Customer/Form/_firstColumn.html.twig`) by adding lines below
-
-```html
-<div class="ui segment">
-    <h4 class="ui dividing header">{{ 'bitbag_sylius_blacklist_plugin.ui.fraud_status'|trans }}</h4>
-    {{ form_row(form.fraudStatus) }}
-</div>
-```
-
-Update your database
-
-```bash
-bin/console doctrine:migrations:migrate
-```
-
-**Note:** If you are running it on production, add the `-e prod` flag to this command.
+---
+### Requirements
 
-Update your database schema:
+We work on stable, supported and up-to-date versions of packages. We recommend you to do the same.
 
-```bash
-bin/console doctrine:schema:update --dump-sql
-```
+| Package       | Version         |
+|---------------|-----------------|
+| PHP           | \>=8.0          |
+| sylius/sylius | 1.12.x - 1.13.x |
+| MySQL         | \>= 5.7         |
+| NodeJS        | \>= 18.x        |
 
-If the list includes only changes for updating the database by adding 'fraud_status' you can use:
-
-```bash
-bin/console doctrine:schema:update -f
-```
+----
 
-If there are another changes, please make sure they will not destroy your database schema.
+### Full installation guide
+- [See the full installation guide](doc/installation.md)
 
 ## Functionalities
 
diff --git a/doc/installation.md b/doc/installation.md
new file mode 100644
index 0000000..1b3b35d
--- /dev/null
+++ b/doc/installation.md
@@ -0,0 +1,218 @@
+# Installation
+
+## Overview:
+GENERAL
+- [Requirements](#requirements)
+- [Composer](#composer)
+- [Basic configuration](#basic-configuration)
+--- 
+BACKEND
+- [Entities](#entities)
+    - [Attribute mapping](#attribute-mapping)
+    - [XML mapping](#xml-mapping)
+- [Repositories](#repositories)
+---
+FRONTEND
+- [Templates](#templates)
+---
+ADDITIONAL
+- [Tests](#tests)
+- [Known Issues](#known-issues)
+---
+
+## Requirements:
+We work on stable, supported and up-to-date versions of packages. We recommend you to do the same.
+
+| Package       | Version         |
+|---------------|-----------------|
+| PHP           | \>8.0           |
+| sylius/sylius | 1.12.x - 1.13.x |
+| MySQL         | \>= 5.7         |
+| NodeJS        | \>= 18.x        |
+
+## Composer:
+```bash
+composer require bitbag/blacklist-plugin --no-scripts
+```
+
+## Basic configuration:
+Add plugin dependencies to your `config/bundles.php` file:
+
+```php
+# config/bundles.php
+
+return [
+    ...
+    BitBag\SyliusBlacklistPlugin\BitBagSyliusBlacklistPlugin::class => ['all' => true],
+];
+```
+
+Import required config in your `config/packages/_sylius.yaml` file:
+
+```yaml
+# config/packages/_sylius.yaml
+
+imports:
+    ...
+    - { resource: "@BitBagSyliusBlacklistPlugin/Resources/config/config.yaml" }
+```
+
+Add routing to your `config/routes.yaml` file:
+```yaml
+# config/routes.yaml
+
+bitbag_sylius_blacklist_plugin:
+    resource: "@BitBagSyliusBlacklistPlugin/Resources/config/routing.yaml"
+```
+
+Override Customer grid in `config/packages/_sylius_grid.yml` file:
+```yaml
+# config/packages/_sylius_grid.yml
+
+sylius_grid:
+    grids:
+        sylius_admin_customer:
+            fields:
+                ...
+                fraudStatus:
+                    type: twig
+                    label: bitbag_sylius_blacklist_plugin.ui.fraud_status
+                    options:
+                        template: "@BitBagSyliusBlacklistPlugin/Customer/Grid/Field/fraudStatus.html.twig"
+            filters:
+                ...
+                fraudStatus:
+                    type: select
+                    label: bitbag_sylius_blacklist_plugin.ui.fraud_status
+                    form_options:
+                        choices:
+                            bitbag_sylius_blacklist_plugin.ui.neutral: Neutral
+                            bitbag_sylius_blacklist_plugin.ui.blacklisted: Blacklisted
+```
+
+Override twig configuration in `config/packages/twig.yml` file:
+```yaml
+# config/packages/twig.yaml
+...
+
+twig:
+    paths: ['%kernel.project_dir%/templates']
+    debug: '%kernel.debug%'
+    strict_variables: '%kernel.debug%'
+    form_themes:
+        - '@BitBagSyliusBlacklistPlugin/Form/theme.html.twig'
+        - '@SyliusUi/Form/theme.html.twig'
+services:
+    _defaults:
+        public: false
+        autowire: true
+        autoconfigure: true
+
+    Twig\Extra\Intl\IntlExtension: ~
+
+when@test_cached:
+    twig:
+        strict_variables: true
+```
+
+## Entities
+You can implement entity configuration by using both xml-mapping and attribute-mapping. Depending on your preference, choose either one or the other:
+### Attribute mapping
+- [Attribute mapping configuration](installation/attribute-mapping.md)
+### XML mapping
+- [XML mapping configuration](installation/xml-mapping.md)
+
+**Note:** If you are running it on production, add the `-e prod` flag to this command.
+
+## Repositories
+Add repository with following trait:
+```php
+<?php
+// src/Repository/CustomerRepository.php
+
+declare(strict_types=1);
+
+namespace App\Repository;
+
+use BitBag\SyliusBlacklistPlugin\Repository\CustomerRepositoryTrait;
+use Sylius\Bundle\CoreBundle\Doctrine\ORM\CustomerRepository as BaseCustomerRepository;
+
+class CustomerRepository extends BaseCustomerRepository
+{
+    use CustomerRepositoryTrait;
+}
+```
+
+Override `config/packages/_sylius.yaml` configuration:
+```yaml
+# config/packages/_sylius.yaml
+...
+
+sylius_customer:
+    resources:
+        customer:
+            classes:
+                ...
+                repository: App\Repository\CustomerRepository
+```
+
+### Update your database
+First, please run legacy-versioned migrations by using command:
+```bash
+bin/console doctrine:migrations:migrate
+```
+
+After migration, please create a new diff migration and update database:
+```bash
+bin/console doctrine:migrations:diff
+bin/console doctrine:migrations:migrate
+```
+
+### Clear application cache by using command:
+```bash
+bin/console cache:clear
+```
+**Note:** If you are running it on production, add the `-e prod` flag to this command.
+
+## Templates
+
+**AdminBundle** (`templates/bundles/SyliusAdminBundle`):
+
+Override Customer form template (`@SyliusAdminBundle\Customer\_form.html.twig`
+or `@SyliusAdminBundle/Customer/Form/_firstColumn.html.twig`) by adding lines below:
+
+```php
+<div class="ui segment">
+    <h4 class="ui dividing header">{{ 'bitbag_sylius_blacklist_plugin.ui.fraud_status'|trans }}</h4>
+    {{ form_row(form.fraudStatus) }}
+</div>
+```
+
+or copy from the path:
+
+```
+vendor/bitbag/blacklist-plugin/tests/Application/templates/bundles/SyliusAdminBundle/Customer/_form.html.twig
+```
+
+## Tests
+To run the tests, execute the commands:
+```bash
+composer install
+cd tests/Application
+yarn install
+yarn build
+bin/console assets:install public -e test
+bin/console doctrine:schema:create -e test
+bin/console server:run 127.0.0.1:8080 -d public -e test
+open http://localhost:8080
+cd ../..
+vendor/bin/behat
+vendor/bin/phpspec run
+```
+
+## Known issues
+### Translations not displaying correctly
+For incorrectly displayed translations, execute the command:
+```bash
+bin/console cache:clear
+```
diff --git a/doc/installation/attribute-mapping.md b/doc/installation/attribute-mapping.md
new file mode 100644
index 0000000..6f588b7
--- /dev/null
+++ b/doc/installation/attribute-mapping.md
@@ -0,0 +1,48 @@
+# Attribute-mapping
+
+Check the mapping settings in `config/packages/doctrine.yaml` and, if necessary, change them accordingly.
+```yaml
+doctrine:
+    ...
+    orm:
+        entity_managers:
+            default:
+                ...
+                mappings:
+                    App:
+                        ...
+                        type: attribute
+```
+
+Extend entities with parameters and methods using attributes and traits:
+
+- `Customer` entity
+
+```php
+<?php
+// src/Entity/Customer/Customer.php
+
+declare(strict_types=1);
+
+namespace App\Entity\Customer;
+
+use BitBag\SyliusBlacklistPlugin\Entity\Customer\FraudStatusInterface;
+use BitBag\SyliusBlacklistPlugin\Model\FraudStatusTrait;
+use Doctrine\ORM\Mapping as ORM;
+use Sylius\Component\Core\Model\Customer as BaseCustomer;
+use Tests\BitBag\SyliusBlacklistPlugin\Entity\CustomerInterface;
+
+/**
+ * @ORM\Entity
+ * @ORM\Table(name="sylius_customer")
+ */
+#[ORM\Entity]
+#[ORM\Table(name: 'sylius_customer')]
+class Customer extends BaseCustomer implements CustomerInterface
+{
+    use FraudStatusTrait;
+
+    #[ORM\Column(type: 'string', nullable: false)]
+    protected $fraudStatus = FraudStatusInterface::FRAUD_STATUS_NEUTRAL;
+}
+```
diff --git a/doc/installation/xml-mapping.md b/doc/installation/xml-mapping.md
new file mode 100644
index 0000000..38cf6ca
--- /dev/null
+++ b/doc/installation/xml-mapping.md
@@ -0,0 +1,86 @@
+# XML-mapping
+
+Check the mapping settings in `config/packages/doctrine.yaml` and, if necessary, change them accordingly.
+```yaml
+doctrine:
+    ...
+doctrine:
+    ...
+    orm:
+        entity_managers:
+            default:
+                ...
+                mappings:
+                    App:
+                        ...
+                        type: xml
+                        dir: '%kernel.project_dir%/src/Resources/config/doctrine'
+```
+
+Extend entities with parameters and methods using attributes and traits:
+
+- `Customer` entity:
+
+```php
+<?php
+// src/Entity/Customer.php
+
+declare(strict_types=1);
+
+namespace App\Entity\Customer;
+
+use BitBag\SyliusBlacklistPlugin\Model\FraudStatusTrait;
+use Sylius\Component\Core\Model\Customer as BaseCustomer;
+
+class Customer extends BaseCustomer implements CustomerInterface
+{
+    use FraudStatusTrait;
+}
+```
+
+Define new Entity mapping inside `src/Resources/config/doctrine` directory.
+
+- `Customer` entity:
+
+`src/Resources/config/doctrine/Customer.orm.xml`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+
+<doctrine-mapping
+        xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd"
+>
+    <entity name="App\Entity\Customer" table="sylius_customer">
+        <field name="fraudStatus" column="fraud_status" type="string" />
+    </entity>
+</doctrine-mapping>
+```
+
+Create also interface, which is implemented by `Customer` entity:
+```php
+<?php
+// src/Entity/CustomerInterface.php
+
+namespace App\Entity\Customer;
+
+use BitBag\SyliusBlacklistPlugin\Entity\Customer\FraudStatusInterface;
+use Sylius\Component\Core\Model\CustomerInterface as BaseCustomerInterface;
+
+interface CustomerInterface extends BaseCustomerInterface, FraudStatusInterface
+{
+}
+```
+
+Override `config/packages/_sylius.yaml` configuration:
+```yaml
+# config/_sylius.yaml
+
+sylius_customer:
+    resources:
+        customer:
+            classes:
+                model: App\Entity\Customer
+```