diff --git a/README.md b/README.md
index fc843710..d2542bd4 100644
--- a/README.md
+++ b/README.md
@@ -18,20 +18,11 @@
 [![Lint Status](https://github.com/kreuzwerker/terraform-provider-docker/workflows/golangci-lint/badge.svg)](https://github.com/kreuzwerker/terraform-provider-docker/actions)
 [![Go Report Card](https://goreportcard.com/badge/github.com/kreuzwerker/terraform-provider-docker)](https://goreportcard.com/report/github.com/kreuzwerker/terraform-provider-docker)  
 
-- Website: https://www.terraform.io
-- Provider: [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker/latest)
-- Slack: [@gophers/terraform-provider-docker](https://gophers.slack.com/archives/C01G9TN5V36)
+## Documentation
 
-## Requirements
--	[Terraform](https://www.terraform.io/downloads.html) >=0.12.x
--	[Go](https://golang.org/doc/install) 1.18.x (to build the provider plugin)
+The documentation for the provider is available on the [Terraform Registry](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs).
 
-## Building The Provider
-
-```sh
-$ git clone git@github.com:kreuzwerker/terraform-provider-docker
-$ make build
-```
+Do you want to migrate from `v2.x` to `v3.x`? Please read the [migration guide](docs/v2_v3_migration.md)
 
 ## Example usage
 
@@ -100,6 +91,16 @@ resource "docker_service" "nginx_service" {
 }
 ```
 
+## Building The Provider
+
+[Go](https://golang.org/doc/install) 1.18.x (to build the provider plugin)
+
+
+```sh
+$ git clone git@github.com:kreuzwerker/terraform-provider-docker
+$ make build
+```
+
 ## Contributing
 
 The Terraform Docker Provider is the work of many of contributors. We appreciate your help!
diff --git a/internal/provider/resource_docker_registry_image.go b/internal/provider/resource_docker_registry_image.go
index 66a68c58..abfaef4d 100644
--- a/internal/provider/resource_docker_registry_image.go
+++ b/internal/provider/resource_docker_registry_image.go
@@ -39,10 +39,10 @@ func resourceDockerRegistryImage() *schema.Resource {
 
 			"build": {
 				Type:        schema.TypeList,
-				Description: "Definition for building the image",
+				Description: "This field is deprecated. Use the `build` block of the `docker_image` resource instead. This field will be removed in the next major release.",
 				Optional:    true,
 				MaxItems:    1,
-				Deprecated:  "Use `docker_image` resource instead. This field will be removed in the next major release.",
+				Deprecated:  "Use the build block fo the `docker_image` resource instead. This field will be removed in the next major release.",
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"suppress_output": {
diff --git a/templates/v2_v3_migration.md b/templates/v2_v3_migration.md
new file mode 100644
index 00000000..9e3d7501
--- /dev/null
+++ b/templates/v2_v3_migration.md
@@ -0,0 +1,47 @@
+# V2 to V3 Migration Guide
+
+This guide is intended to help you migrate from V2 to V3 of the `terraform-provider-docker`.
+
+The in the past minor versions there were many new attributes and older attributes are deprecated. 
+
+This will give you an overview over which attributes are deprecated and which attributes you should use instead.
+
+## `docker_container`
+
+
+Deprecated attributes:
+* `links`: The --link flag is a legacy feature of Docker and will be removed (https://docs.docker.com/network/links/)
+* `ip_address`, `ip_prefix_length`, `gateway`: Use the `network_data` block instead
+* `network_alias`, `networks`: Use the `networks_addvanced` block instead
+
+
+## `docker_image`
+
+* `latest`: Use `repo_digest` instead
+* `pull_trigger`: Use `pull_triggers` instead
+* `output`: Unused and will be removed
+* `build.path`: Use `build.context` instead
+
+## `docker_service`
+
+* `networks`: Use the `networks_addvanced` block instead
+
+
+## `docker_registry_image`
+
+The whole `build` block will be removed. Use the `build` block of the `docker_image` resource instead.
+In order to push images to an registry, still use `docker_registry_image` and reference the `docker_image` resource:
+
+```hcl
+resource "docker_image" "foo_image" {
+  provider = "docker.private"
+  name     = "somename"
+  build {
+   // your build params
+  }
+}
+
+resource "docker_registry_image" "foo" {
+  name                 = docker_image.foo_image.name
+}
+```
\ No newline at end of file