diff --git a/README.adoc b/README.adoc
index cfd39fd3..eb4276bc 100644
--- a/README.adoc
+++ b/README.adoc
@@ -34,6 +34,68 @@ This project contains the SDK for the communication with the agrirouter. Everyth
 
 The release workflow follows the https://docs.microsoft.com/en-us/azure/devops/repos/git/git-branching-guidance?view=azure-devops[Microsoft DevOps Release Model] where a release shows up as a branch in the repository.
 
+=== Update from 1.4.x to 2.x
+
+The update for the new release includes some breaking changes. To have a rough overview what has to be done to have the new features from 2.x in you application, please see the following migration / update guide when updating.
+
+==== Update the Maven dependencies
+
+The first step is to update the coordinates of the dependencies. With the release 2.x the coordinates changed to a new name and a new version.
+
+[xml]
+----
+    <dependency>
+        <groupId>com.agrirouter.api</groupId>
+        <artifactId>agrirouter-sdk-java-api</artifactId>
+        <version>2.0.0</version>
+    </dependency>
+    <dependency>
+        <groupId>com.agrirouter.api</groupId>
+        <artifactId>agrirouter-sdk-java-impl</artifactId>
+        <version>2.0.0</version>
+    </dependency>
+    <dependency>
+        <groupId>com.agrirouter.api</groupId>
+        <artifactId>agrirouter-sdk-java-convenience</artifactId>
+        <version>2.0.0</version>
+    </dependency>
+----
+
+==== Update package declarations for services and internal classes
+
+Since the package declaration was updated along with the coordinates, there will be compiler errors that should be fixed. Some classes have moved to a more meaningful package.
+
+image::migration_1-4_to_2-0/compiler-errors-before.png[Compiler errors before the migration.]
+
+The new package declaration added the protocol part (`http` or in this case the `mqtt`).
+
+image::migration_1-4_to_2-0/package-declaration-after-refactoring.png[Package declaration after migrating.]
+
+==== Update the usage of the enums for message types
+
+To have a better understanding about system message types and content message types, the declaration for the different types has changed. There are two new classes, the `ContentMessageType` for content messages and the `SystemMessageType` for system messages. The former technical message type will cause a compiler error, since it was replaced.
+
+image::migration_1-4_to_2-0/former-technical-message-types.png[Former message types.]
+
+The new declaration uses the system message type.
+
+image::migration_1-4_to_2-0/system-message-type-afterwards.png[System message type usage afterwards.]
+
+==== Remove former URLs for ProtoBuf message types
+
+With the new release the URLs can be fetched from the content message types and there is no need to put them into a helper method any longer.
+
+image::migration_1-4_to_2-0/former-content-message-type-urls.png[Former content message types.]
+
+With the new release fetch the URLs is way more comfortable.
+
+image::migration_1-4_to_2-0/type-urls-from-technical-message-types.png[Type URLs from content message types.]
+
+==== Have a look at an example
+
+The http://www.agrirouter-middleware[agrirouter middleware] has been updated after the release of version 2.x and can be an indicator regarding the workload for the migration.
+Have a look at the following https://github.com/agrirouter-middleware/agrirouter-middleware/pull/12[PR #12] to see the necessary adaptions.
+
 == Modules
 
 === `api` Module
diff --git a/assets/images/migration_1-4_to_2-0/compiler-errors-before.png b/assets/images/migration_1-4_to_2-0/compiler-errors-before.png
new file mode 100644
index 00000000..8f113470
Binary files /dev/null and b/assets/images/migration_1-4_to_2-0/compiler-errors-before.png differ
diff --git a/assets/images/migration_1-4_to_2-0/former-content-message-type-urls.png b/assets/images/migration_1-4_to_2-0/former-content-message-type-urls.png
new file mode 100644
index 00000000..e49c2350
Binary files /dev/null and b/assets/images/migration_1-4_to_2-0/former-content-message-type-urls.png differ
diff --git a/assets/images/migration_1-4_to_2-0/former-technical-message-types.png b/assets/images/migration_1-4_to_2-0/former-technical-message-types.png
new file mode 100644
index 00000000..95d9936d
Binary files /dev/null and b/assets/images/migration_1-4_to_2-0/former-technical-message-types.png differ
diff --git a/assets/images/migration_1-4_to_2-0/package-declaration-after-refactoring.png b/assets/images/migration_1-4_to_2-0/package-declaration-after-refactoring.png
new file mode 100644
index 00000000..f45fb27d
Binary files /dev/null and b/assets/images/migration_1-4_to_2-0/package-declaration-after-refactoring.png differ
diff --git a/assets/images/migration_1-4_to_2-0/system-message-type-afterwards.png b/assets/images/migration_1-4_to_2-0/system-message-type-afterwards.png
new file mode 100644
index 00000000..70348311
Binary files /dev/null and b/assets/images/migration_1-4_to_2-0/system-message-type-afterwards.png differ
diff --git a/assets/images/migration_1-4_to_2-0/type-urls-from-technical-message-types.png b/assets/images/migration_1-4_to_2-0/type-urls-from-technical-message-types.png
new file mode 100644
index 00000000..7eae591f
Binary files /dev/null and b/assets/images/migration_1-4_to_2-0/type-urls-from-technical-message-types.png differ