From e014ecf9a3888f8a8b5f439ce778da1060dd7cd9 Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Mon, 15 Apr 2024 13:20:39 +0200
Subject: [PATCH] Update documentation

---
 docs/resources/app.md                            | 12 ++++++++++--
 .../provider/resource/appresource/resource.go    | 16 ++++++++++------
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/docs/resources/app.md b/docs/resources/app.md
index de78e87..23c76b4 100644
--- a/docs/resources/app.md
+++ b/docs/resources/app.md
@@ -99,8 +99,16 @@ resource "mittwald_app" "custom_php" {
 
 ### Optional
 
-- `databases` (Attributes Set) The databases the app uses (see [below for nested schema](#nestedatt--databases))
-- `dependencies` (Attributes Map) The dependencies of the app (see [below for nested schema](#nestedatt--dependencies))
+- `databases` (Attributes Set) The databases the app uses.
+
+    You can use this field to link databases to the app. The database resources must be created before the app resource, and the database resources must have the same project ID as the app resource.
+
+    This is only necessary if the specific app is not implicitly linked to a database by the backend. This is the case for apps like WordPress or TYPO3, which are always linked to a database. In these cases, you can (or should, even) omit the `databases` attribute. You can still retrieve the linked databases from the observed state, but you should not manage them manually. (see [below for nested schema](#nestedatt--databases))
+- `dependencies` (Attributes Map) The dependencies of the app.
+
+    You can omit these to use the suggested dependencies for the app (in which case you can later select the dependencies from the resource state).
+
+    If you specify dependencies, you must specify the exact version of the dependency. To select a version using a semantic versioning constraint, use the `mittwald_systemsoftware` data source. (see [below for nested schema](#nestedatt--dependencies))
 - `description` (String) The description of the app
 - `document_root` (String) The document root of the app
 - `user_inputs` (Map of String) The user inputs of the app
diff --git a/internal/provider/resource/appresource/resource.go b/internal/provider/resource/appresource/resource.go
index 37ceff1..b13c399 100644
--- a/internal/provider/resource/appresource/resource.go
+++ b/internal/provider/resource/appresource/resource.go
@@ -70,9 +70,11 @@ func (r *Resource) Schema(_ context.Context, _ resource.SchemaRequest, resp *res
 				},
 			},
 			"databases": schema.SetNestedAttribute{
-				MarkdownDescription: "The databases the app uses",
-				Optional:            true,
-				Computed:            true,
+				MarkdownDescription: "The databases the app uses.\n\n" +
+					"    You can use this field to link databases to the app. The database resources must be created before the app resource, and the database resources must have the same project ID as the app resource.\n\n" +
+					"    This is only necessary if the specific app is not implicitly linked to a database by the backend. This is the case for apps like WordPress or TYPO3, which are always linked to a database. In these cases, you can (or should, even) omit the `databases` attribute. You can still retrieve the linked databases from the observed state, but you should not manage them manually.",
+				Optional: true,
+				Computed: true,
 				NestedObject: schema.NestedAttributeObject{
 					Attributes: map[string]schema.Attribute{
 						"id": schema.StringAttribute{
@@ -140,9 +142,11 @@ func (r *Resource) Schema(_ context.Context, _ resource.SchemaRequest, resp *res
 				ElementType:         types.StringType,
 			},
 			"dependencies": schema.MapNestedAttribute{
-				MarkdownDescription: "The dependencies of the app",
-				Optional:            true,
-				Computed:            true,
+				MarkdownDescription: "The dependencies of the app.\n\n" +
+					"    You can omit these to use the suggested dependencies for the app (in which case you can later select the dependencies from the resource state).\n\n" +
+					"    If you specify dependencies, you must specify the exact version of the dependency. To select a version using a semantic versioning constraint, use the `mittwald_systemsoftware` data source.",
+				Optional: true,
+				Computed: true,
 				NestedObject: schema.NestedAttributeObject{
 					Attributes: map[string]schema.Attribute{
 						"version": schema.StringAttribute{