diff --git a/modules/azure-disks/.terraform-docs.yml b/modules/azure-disks/.terraform-docs.yml
new file mode 100644
index 000000000..bce3ca3a9
--- /dev/null
+++ b/modules/azure-disks/.terraform-docs.yml
@@ -0,0 +1,48 @@
+formatter: "markdown" # this is required
+
+version: ""
+
+header-from: docs/header.md
+footer-from: docs/footer.md
+
+recursive:
+  enabled: false
+  path: modules
+  include-main: true
+
+sections:
+  hide: []
+  show: []
+
+content: ""
+
+output:
+  file: "README.md"
+  mode: inject
+  template: |-
+    <!-- BEGIN_TF_DOCS -->
+    {{ .Content }}
+    <!-- END_TF_DOCS -->
+
+output-values:
+  enabled: false
+  from: ""
+
+sort:
+  enabled: true
+  by: name
+
+settings:
+  anchor: true
+  color: true
+  default: true
+  description: false
+  escape: true
+  hide-empty: false
+  html: true
+  indent: 2
+  lockfile: true
+  read-comments: true
+  required: true
+  sensitive: true
+  type: true
\ No newline at end of file
diff --git a/modules/azure-disks/README.md b/modules/azure-disks/README.md
index 4b40aeab3..6e81acc50 100644
--- a/modules/azure-disks/README.md
+++ b/modules/azure-disks/README.md
@@ -1,3 +1,54 @@
+<!-- BEGIN_TF_DOCS -->
+# Azure Managed Disks Terraform Module
+
+## Overview
+
+This Terraform module allows you to create and manage managed disks in Azure, with support for:
+- Creation of multiple disks with different configurations.
+- Optional role assignment on disks.
+- Flexible tagging and tag inheritance from the Resource Group.
+
+## Main features
+- Create managed disks of different types and sizes.
+- Optional role assignment to disks (e.g., Contributor).
+- Support for tags and inheritance from the Resource Group.
+- Ignores disk size changes in lifecycle (useful for CSI Driver).
+
+## Complete usage example
+
+```yaml
+values:
+  tags_from_rg: true
+  resource_group_name: "REDACTED-RESOURCE-GROUP"
+  location: "REDACTED-LOCATION"
+  disks:
+      - name: disk-1
+        storage_account_type: StandardSSD_LRS
+      - name: disk-2
+      - name: disk-3
+      - name: disk-4
+```
+
+## Notes
+- You can create empty disks or base them on another disk.
+- Assigning a role to a disk is not mandatory.
+- Disk size is ignored in changes to avoid conflicts with the CSI Driver.
+
+## File structure
+
+```
+.
+├── main.tf
+├── variables.tf
+├── outputs.tf
+├── versions.tf
+├── README.md
+├── CHANGELOG.md
+└── docs/
+    ├── header.md
+    └── footer.md
+```
+
 ## Requirements
 
 | Name | Version |
@@ -11,6 +62,10 @@
 |------|---------|
 | <a name="provider_azurerm"></a> [azurerm](#provider\_azurerm) | ~> 4.5.0 |
 
+## Modules
+
+No modules.
+
 ## Resources
 
 | Name | Type |
@@ -39,25 +94,21 @@
 | <a name="output_disk_ids"></a> [disk\_ids](#output\_disk\_ids) | n/a |
 | <a name="output_disk_names"></a> [disk\_names](#output\_disk\_names) | Output section |
 
-## Notes
+---
 
-- Empty disks or disks based on another disk can be created.
-- It is not necessary to assign a role to a disk.
-- **There is a lifecycle rule to ignore changes to disk size, as the CSI Driver may resize the disk outside of Terraform.**
+## Examples
 
-## Example
+For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azure-disks/_examples):
 
-```yaml
-values:
-  tags_from_rg: true
-  resource_group_name: "REDACTED-RESOURCE-GROUP"
-  location: "REDACTED-LOCATION"
-  disks:
-      - name: disk-1
-        storage_account_type: StandardSSD_LRS
-      - name: disk-2
-      - name: disk-3
-      - name: disk-4
-        storage_account_type: Premium_LRS
-  principal_id: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
-```
+- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-disks/_examples/basic) - Basic managed disk configuration with size, SKU and performance settings.
+
+## Additional resources
+
+- [Azure Managed Disks](https://learn.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview)
+- [Terraform AzureRM Provider - azurerm\_managed\_disk](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/managed_disk)
+- [Official Terraform documentation](https://www.terraform.io/docs)
+
+## Support
+
+For issues, questions, or contributions related to this module, please visit the repository’s issue tracker: [https://github.com/prefapp/tfm/issues](https://github.com/prefapp/tfm/issues)
+<!-- END_TF_DOCS -->
\ No newline at end of file
diff --git a/modules/azure-disks/_examples/basic/main.tf b/modules/azure-disks/_examples/basic/main.tf
new file mode 100644
index 000000000..9eadbe078
--- /dev/null
+++ b/modules/azure-disks/_examples/basic/main.tf
@@ -0,0 +1,30 @@
+// Basic example: create managed disks using the azure-disks module
+
+module "azure_disks" {
+  source = "../../"
+
+  location            = "westeurope"
+  resource_group_name = "example-rg"
+
+  disks = {
+    data1 = {
+      # This map is intentionally loose; adapt keys to match main.tf expectations.
+      size_gb             = 128
+      sku                 = "Premium_LRS"
+      zone                = "1"
+      create_option       = "Empty"
+      encryption_type     = "EncryptionAtRestWithPlatformKey"
+      disk_iops_read_write = 500
+      disk_mbps_read_write = 100
+    }
+  }
+
+  assign_role         = false
+  role_definition_name = "Contributor"
+  principal_id        = ""
+
+  tags = {
+    environment = "dev"
+    application = "example"
+  }
+}
\ No newline at end of file
diff --git a/modules/azure-disks/_examples/basic/values.yaml b/modules/azure-disks/_examples/basic/values.yaml
new file mode 100644
index 000000000..a8a2a707e
--- /dev/null
+++ b/modules/azure-disks/_examples/basic/values.yaml
@@ -0,0 +1,22 @@
+# Basic example values for azure-disks module
+
+location: westeurope
+resource_group_name: example-rg
+
+disks:
+  data1:
+    size_gb: 128
+    sku: Premium_LRS
+    zone: "1"
+    create_option: Empty
+    encryption_type: EncryptionAtRestWithPlatformKey
+    disk_iops_read_write: 500
+    disk_mbps_read_write: 100
+
+assign_role: false
+role_definition_name: Contributor
+principal_id: ""
+
+tags:
+  environment: dev
+  application: example
\ No newline at end of file
diff --git a/modules/azure-disks/docs/footer.md b/modules/azure-disks/docs/footer.md
new file mode 100644
index 000000000..82e0e30de
--- /dev/null
+++ b/modules/azure-disks/docs/footer.md
@@ -0,0 +1,17 @@
+---
+
+## Examples
+
+For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azure-disks/_examples):
+
+- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-disks/_examples/basic) - Basic managed disk configuration with size, SKU and performance settings.
+
+## Additional resources
+
+- [Azure Managed Disks](https://learn.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview)
+- [Terraform AzureRM Provider - azurerm_managed_disk](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/managed_disk)
+- [Official Terraform documentation](https://www.terraform.io/docs)
+
+## Support
+
+For issues, questions, or contributions related to this module, please visit the repository’s issue tracker: [https://github.com/prefapp/tfm/issues](https://github.com/prefapp/tfm/issues)
\ No newline at end of file
diff --git a/modules/azure-disks/docs/header.md b/modules/azure-disks/docs/header.md
new file mode 100644
index 000000000..e4f2e286a
--- /dev/null
+++ b/modules/azure-disks/docs/header.md
@@ -0,0 +1,49 @@
+# Azure Managed Disks Terraform Module
+
+## Overview
+
+This Terraform module allows you to create and manage managed disks in Azure, with support for:
+- Creation of multiple disks with different configurations.
+- Optional role assignment on disks.
+- Flexible tagging and tag inheritance from the Resource Group.
+
+## Main features
+- Create managed disks of different types and sizes.
+- Optional role assignment to disks (e.g., Contributor).
+- Support for tags and inheritance from the Resource Group.
+- Ignores disk size changes in lifecycle (useful for CSI Driver).
+
+## Complete usage example
+
+```yaml
+values:
+  tags_from_rg: true
+  resource_group_name: "REDACTED-RESOURCE-GROUP"
+  location: "REDACTED-LOCATION"
+  disks:
+      - name: disk-1
+        storage_account_type: StandardSSD_LRS
+      - name: disk-2
+      - name: disk-3
+      - name: disk-4
+```
+
+## Notes
+- You can create empty disks or base them on another disk.
+- Assigning a role to a disk is not mandatory.
+- Disk size is ignored in changes to avoid conflicts with the CSI Driver.
+
+## File structure
+
+```
+.
+├── main.tf
+├── variables.tf
+├── outputs.tf
+├── versions.tf
+├── README.md
+├── CHANGELOG.md
+└── docs/
+    ├── header.md
+    └── footer.md
+```
\ No newline at end of file