refactor prefix docs

README.md

@@ -23,13 +23,15 @@ You can see the published documentation at https://terraform-ibm-modules.github.
     - [About merging pull requests](https://terraform-ibm-modules.github.io/documentation/#/merging.md)
 - Reference
     - [Module authoring guidelines](https://terraform-ibm-modules.github.io/documentation/#/implementation-guidelines.md)
-    - [Deployable Architecture authoring guidelines](https://terraform-ibm-modules.github.io/documentation/#/da-implementation-guidelines.md)
+    - [DA authoring guidelines](https://terraform-ibm-modules.github.io/documentation/#/da-implementation-guidelines.md)
     - [Design guidelines](https://terraform-ibm-modules.github.io/documentation/#/design-guidelines.md)
     - [Module structure](https://terraform-ibm-modules.github.io/documentation/#/module-structure.md)
     - [Metadata file (index.yml)](https://terraform-ibm-modules.github.io/documentation/#/module-catalog-metadata.md)
     - [About module badges](https://terraform-ibm-modules.github.io/documentation/#/badge-status.md)
     - [Release versioning](https://terraform-ibm-modules.github.io/documentation/#/versioning.md)
     - Governance
+- DA consumer tips
+    - [Prefix](https://terraform-ibm-modules.github.io/documentation/#/prefix.md)
 - Troubleshooting
     - [Known issues](https://terraform-ibm-modules.github.io/documentation/#/issues.md)
     - [How do I address errors when I run tests?](https://terraform-ibm-modules.github.io/documentation/#/ts-go-cache.md)

docs/_sidebar.md

@@ -13,13 +13,15 @@
     - [About merging pull requests](merging.md)
 - Reference
     - [Module authoring guidelines](implementation-guidelines.md)
-    - [Deployable Architecture authoring guidelines](da-implementation-guidelines.md)
+    - [DA authoring guidelines](da-implementation-guidelines.md)
     - [Design guidelines](design-guidelines.md)
     - [Module structure](module-structure.md)
     - [Metadata file (index.yml)](module-catalog-metadata.md)
     - [About module badges](badge-status.md)
     - [Release versioning](versioning.md)
     - Governance
+- DA consumer tips
+    - [Prefix](prefix.md)
 - Troubleshooting
     - [Known issues](issues.md)
     - [How do I address errors when I run tests?](ts-go-cache.md)

docs/da-implementation-guidelines.md

@@ -1,51 +1,40 @@
 # Deployable Architecture authoring guidelines
 
-## Prefix in Deployable Architecture
-
-The **`prefix`** input variable allows you to prepend a custom string to the names of all resources created by this automation. This is especially useful for:
-
-- **Avoiding naming collisions** when deploying the same solution multiple times within the same account.
-- **Creating identical infrastructure** across multiple regions or environments.
-- **Improving resource traceability** by embedding environment or region identifiers into resource names.
-
-If you do not wish to use a prefix, you may set the value to `null` or an empty string (`""`).
-
-**Important**: The automation automatically inserts a hyphen between the prefix and the resource name. Therefore, you do not need to include a hyphen in the prefix yourself.
-
-### Examples
-
-Here are some common patterns for using the prefix:
-
-- **Environment-based**:
-  - `dev`, `test`, `prod`
-- **Environment + Region**:
-  - `dev-eu-gb`, `prod-us-south`, `test-jp-tok`
-- **Project-specific**:
-  - `webapp-dev`, `ml-prod`, `iot-test`
-- **Team or department identifiers**:
-  - `fin-dev`, `hr-prod`, `eng-test`
-- **Date or version-based** (for temporary or experimental deployments):
-  - `exp-202505`, `v2-dev`
-
-These conventions help ensure that resources are clearly grouped and easily identifiable, especially in shared or multi-tenant accounts.
-
-### Naming Rules
-
-To ensure compatibility and consistency, the prefix must follow these rules:
-
-- Must begin with a **lowercase letter**
-- May contain only **lowercase letters**, **digits**, and **hyphens (`-`)**
-- Must **not end** with a hyphen (`-`)
-- Must **not contain consecutive hyphens** (`--`)
-- Maximum length: **16 characters**
+Below you will find some guidance on best practises that should be used when authoring a new Deployable Architecture (DA). In addition, there is some common guidance available in the following links:
+- [Best practices for creating deployable architectures](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-best-practice-deployable-arch)
+- [Best practices for Terraform on IBM Cloud](https://cloud.ibm.com/docs/terraform-on-ibm-cloud?topic=terraform-on-ibm-cloud-white-paper#deployable-architecture-overview)
+
+## Prefix
+
+All Deployable Architecture solutions should have an optional **`prefix`** input variable that complies with the following criteria:
+- Input should have no default value, but set `nullable = true` to allow user to pass `null` incase they do not wish to use a prefix. This would be for advanced users who may need full control over resource naming.
+- Add validation to the variable. See the below code snippet for the recommended validation to be added across all DAs. Ideally all DAs should have the same validation so the `prefix` value is accepted for all DAs for the case where it may be used for input mapping when configuring dependant (add-on) DAs.
+- Ensure to include the details of the required format in the variable description, an example value, and link to the helper doc just like what is shown in the code snippet below. This should be consistent across all DAs.
+- The prefix variable logic should be handled in a local variable so logic does not have repeated in the terraform code. For example:
+  ```hcl
+  locals {
+    prefix        = var.prefix != null ? trimspace(var.prefix) != "" ? "${var.prefix}-" : "" : ""
+    instance_name = "${local.prefix}${var.instance_name}"
+  }
+  ```
+- Ensure that every variable that will use the prefix includes details about the prefix in the variable description. For example:
+  ```hcl
+  variable "instance_name" {
+    type        = string
+    default     = "instance"
+    description = "The name for the <some service> instance provisioned by this solution. If a prefix input variable is specified, the prefix is added to the name in the `<prefix>-<instance_name>` format."
+    nullable    = false
+  }
+  ```
 
-Here is the code snippet for your reference.
+### Code snippet example
+The following code should be used consistently across all DAs (tweak the example value that is included in the description so it is relevant to the DA being created):
 
 ```hcl
 variable "prefix" {
   type        = string
   nullable    = true
-  description = "The prefix to be added to all resources created by this solution. To skip using a prefix, set this value to null or an empty string. The prefix must begin with a lowercase letter and may contain only lowercase letters, digits, and hyphens '-'. It should not exceed 16 characters, must not end with a hyphen('-'), and can not contain consecutive hyphens ('--'). Example: prod-0205-cos."
+  description = "The prefix to be added to all resources created by this solution. To skip using a prefix, set this value to null or an empty string. The prefix must begin with a lowercase letter and may contain only lowercase letters, digits, and hyphens '-'. It should not exceed 16 characters, must not end with a hyphen('-'), and can not contain consecutive hyphens ('--'). Example: prod-0205-cos. [Learn more](https://terraform-ibm-modules.github.io/documentation/#/prefix.md)."
 
   validation {
   # - null and empty string is allowed

docs/prefix.md

@@ -0,0 +1,38 @@
+# Prefix in Deployable Architecture
+
+The **`prefix`** input variable allows you to prepend a custom string to the names of all resources created by this automation. This is especially useful for:
+
+- **Avoiding naming collisions** when deploying the same solution multiple times within the same account.
+- **Creating identical infrastructure** across multiple regions or environments.
+- **Improving resource traceability** by embedding environment or region identifiers into resource names.
+
+If you do not wish to use a prefix, you may set the value to `null` or an empty string (`""`).
+
+**Important**: The automation automatically inserts a hyphen between the prefix and the resource name. Therefore, you do not need to include a hyphen in the prefix yourself.
+
+### Examples
+
+Here are some common patterns for using the prefix:
+
+- **Environment-based**:
+  - `dev`, `test`, `prod`
+- **Environment + Region**:
+  - `dev-eu-gb`, `prod-us-south`, `test-jp-tok`
+- **Project-specific**:
+  - `webapp-dev`, `ml-prod`, `iot-test`
+- **Team or department identifiers**:
+  - `fin-dev`, `hr-prod`, `eng-test`
+- **Date or version-based** (for temporary or experimental deployments):
+  - `exp-202505`, `v2-dev`
+
+These conventions help ensure that resources are clearly grouped and easily identifiable, especially in shared or multi-tenant accounts.
+
+### Naming Rules
+
+To ensure compatibility and consistency, the prefix must follow these rules:
+
+- Must begin with a **lowercase letter**
+- May contain only **lowercase letters**, **digits**, and **hyphens (`-`)**
+- Must **not end** with a hyphen (`-`)
+- Must **not contain consecutive hyphens** (`--`)
+- Maximum length: **16 characters**