docs(review): review of documentation pages

docs/data-sources/bloc_snapshot.md

@@ -5,9 +5,17 @@ page_title: "Scaleway: scaleway_block_snapshot"
 
 # scaleway_block_snapshot
 
-Gets information about a Block Snapshot.
+The `scaleway_block_snapshot` data source is used to retrieve information about a Block Storage volume snapshot.
 
-## Example Usage
+Refer to the Block Storage [product documentation](https://www.scaleway.com/en/docs/storage/block/) and [API documentation](https://www.scaleway.com/en/developers/api/block/) for more information.
+
+## Retrieve a volume's snapshot
+
+The following commands allow you to:
+
+- retrieve a snapshot specified by its name
+- retrieve a snapshot specified by its name and the ID of the Block Storage volume it is associated with
+- retrieve a snapshot specified by its ID
 
 ```terraform
 // Get info by snapshot name
@@ -29,14 +37,14 @@ data "scaleway_block_snapshot" "my_snapshot" {
 
 ## Argument Reference
 
-The following arguments are supported:
+This section lists the arguments that you can provide to the `scaleway_block_snapshot` data source to filter and retrieve the desired snapshot. Each argument has a specific purpose:
 
-- `snapshot_id` - (Optional) The ID of the snapshot. Only one of `name` and `snapshot_id` should be specified.
-- `name` - (Optional) The name of the snapshot. Only one of `name` and `snapshot_id` should be specified.
-- `volume_id` - (Optional) The ID of the volume from which the snapshot has been created.
-- `zone` - (Defaults to [provider](../index.md#zone) `zone`) The [zone](../guides/regions_and_zones.md#zones) in which the snapshot exists.
-- `project_id` - (Optional) The ID of the project the snapshot is associated with.
+- `snapshot_id` - (Optional) The unique identifier of the snapshot. Only one of `name` and `snapshot_id` should be specified.
+- `name` - (Optional) The name of the snapshot. Only one of name or snapshot_id should be specified.
+- `volume_id` - (Optional) The unique identifier of the volume from which the snapshot was created.
+- `zone` - (Defaults to the zone specified in the [provider configuration](../index.md#zone)) The [zone](../guides/regions_and_zones.md#zones) in which the snapshot exists.
+- `project_id` - (Optional) The unique identifier of the Project to which the snapshot is associated.
 
 ## Attributes Reference
 
-Exported attributes are the ones from `scaleway_block_snapshot` [resource](../resources/block_snapshot.md)
+The `scaleway_block_snapshot` data source exports certain attributes once the snapshot information is retrieved. These attributes can be referenced in other parts of your Terraform configuration. The exported attributes are those that come from the `scaleway_block_snapshot` [resource](../resources/block_snapshot.md)

docs/data-sources/block_volume.md

@@ -5,9 +5,16 @@ page_title: "Scaleway: scaleway_block_volume"
 
 # scaleway_block_volume
 
-Gets information about a Block Volume.
+The `scaleway_block_volume` data source is used to retrieve information about a Block Storage volume.
+Refer to the Block Storage [product documentation](https://www.scaleway.com/en/docs/storage/block/) and [API documentation](https://www.scaleway.com/en/developers/api/block/) for more information.
+
+## Retrieve a Block Storage volume
+
+The following commands allow you to:
+
+- retrieve a Block Storage volume specified by its name
+- retrieve a Block Storage volume specified by its ID
 
-## Example Usage
 
 ```terraform
 // Get info by volume name
@@ -23,13 +30,13 @@ data "scaleway_block_volume" "my_volume" {
 
 ## Argument Reference
 
-The following arguments are supported:
+This section lists the arguments that you can provide to the `scaleway_block_volume` data source to filter and retrieve the desired volume.
 
-- `volume_id` - (Optional) The ID of the volume. Only one of `name` and `volume_id` should be specified.
+- `volume_id` - (Optional) The unique identifier of the volume. Only one of `name` and `volume_id` should be specified.
 - `name` - (Optional) The name of the volume. Only one of `name` and `volume_id` should be specified.
-- `zone` - (Defaults to [provider](../index.md#zone) `zone`) The [zone](../guides/regions_and_zones.md#zones) in which the volume exists.
-- `project_id` - (Optional) The ID of the project the volume is associated with.
+- `zone` - (Defaults to the zone specified in the [provider configuration](../index.md#zone)). The [zone](../guides/regions_and_zones.md#zones) in which the volume exists.
+- `project_id` - (Optional) The unique identifier of the Project to which the volume is associated.
 
 ## Attributes Reference
 
-Exported attributes are the ones from `scaleway_block_volume` [resource](../resources/block_volume.md)
+The `scaleway_block_volume` data source exports certain attributes once the volume information is retrieved. These attributes can be referenced in other parts of your Terraform configuration. The exported attributes are those that come from the `scaleway_block_volume` [resource](../resources/block_volume.md).

docs/data-sources/cockpit.md

@@ -8,39 +8,48 @@ page_title: "Scaleway: scaleway_cockpit"
 ~> **Important:**  The data source `scaleway_cockpit` has been deprecated and will no longer be supported. Instead, use resource `scaleway_cockpit`.
 
 -> **Note:**
-As of April 2024, Cockpit has introduced regionalization to offer more flexibility and resilience.
-If you have customized dashboards in Grafana for monitoring Scaleway resources, please update your queries to accommodate the new regionalized [data sources](../resources/cockpit_source.md).
+As of April 2024, Cockpit has introduced [regionalization](https://www.scaleway.com/en/docs/observability/cockpit/concepts/#region) to offer more flexibility and resilience.
+If you have created customized dashboards with data for your Scaleway resources before April 2024, you will need to update your queries in Grafana, with the new regionalized [data sources](../resources/cockpit_source.md).
 
-Gets information about the Scaleway Cockpit.
+The `scaleway_cockpit` data source is used to retrieve information about a Scaleway Cockpit associated with a given Project. This can be the default Project or a specific Project identified by its ID.
 
-For more information consult the [documentation](https://www.scaleway.com/en/docs/observability/cockpit/concepts/).
+Refer to Cockpit's [product documentation](https://www.scaleway.com/en/docs/observability/cockpit/concepts/) and [API documentation](https://www.scaleway.com/en/developers/api/cockpit/regional-api) for more information.
 
-## Example Usage
+## Retrieve a Cockpit
+
+The following commands allow you to:
+
+- get information on the Cockpit associated with your Scaleway default Project
+- get information on the Cockpit associated with a specific Scaleway Project
 
 ```hcl
-// Get default project's cockpit
+// Get the default Project's Cockpit
 data "scaleway_cockpit" "main" {}
 ```
 
 ```hcl
-// Get a specific project's cockpit
+// Get a specific Project's Cockpit
 data "scaleway_cockpit" "main" {
   project_id = "11111111-1111-1111-1111-111111111111"
 }
 ```
 
-## Arguments Reference
+## Argument Reference
+
+This section lists the arguments that you can provide to the `scaleway_cockpit` data source to filter and retrieve the desired Cockpit.
+
+- `project_id` - Specifies the ID of the Scaleway Project that the Cockpit is associated with. If not specified, it defaults to the Project ID specified in the [provider configuration](../index.md#project_id).
 
-- `project_id` - (Defaults to [provider](../index.md#project_id) `project_id`) The ID of the project the cockpit is associated with.
+- `plan` - (Optional) Specifies the name or ID of the pricing plan to use.
 
 
 ## Attributes Reference
 
-In addition to all arguments above, the following attributes are exported:
+The `scaleway_cockpit` data source exports certain attributes once the Cockpit information is retrieved. These attributes can be referenced in other parts of your Terraform configuration.
 
-- `plan_id` - (Deprecated) The ID of the current plan
-- `endpoints` - (Deprecated) Endpoints
-    - `metrics_url` - (Deprecated) The metrics URL
-    - `logs_url` - (Deprecated) The logs URL
-    - `alertmanager_url` - (Deprecated) The alertmanager URL
-    - `grafana_url` - (Deprecated) The grafana URL
+- `plan_id` - (Deprecated) ID of the current pricing plan
+- `endpoints` - (Deprecated) A list of [endpoints](https://www.scaleway.com/en/docs/observability/cockpit/concepts/#endpoints) related to Cockpit, each with specific URLs:
+    - `metrics_url` - (Deprecated) URL for [metrics](https://www.scaleway.com/en/docs/observability/cockpit/concepts/#metric) to retrieve in the [Data sources tab](https://console.scaleway.com/cockpit/dataSource) of the Scaleway console.
+    - `logs_url` - (Deprecated) URL for [logs](https://www.scaleway.com/en/docs/observability/cockpit/concepts/#logs) to retrieve in the [Data sources tab](https://console.scaleway.com/cockpit/dataSource) of the Scaleway console.
+    - `alertmanager_url` - (Deprecated) URL for the [Alert manager](https://www.scaleway.com/en/docs/observability/cockpit/concepts/#alert-manager).
+    - `grafana_url` - (Deprecated) URL for Grafana.

docs/data-sources/cockpit_plan.md

@@ -4,9 +4,15 @@ page_title: "Scaleway: scaleway_cockpit_plan"
 ---
 # scaleway_cockpit_plan
 
-Gets information about a Scaleway Cockpit plan.
+The `scaleway_cockpit_plan` data source is used to fetch details about a specific Scaleway Cockpit pricing plan. This information can then be used to configure resources like `scaleway_cockpit`.
 
-## Example Usage
+Find out more about [pricing plans](https://console.scaleway.com/cockpit/plans) in the Scaleway console.
+
+Refer to Cockpit's [product documentation](https://www.scaleway.com/en/docs/observability/cockpit/concepts/) and [API documentation](https://www.scaleway.com/en/developers/api/cockpit/regional-api) for more information.
+
+## Fetch and associate a pricing plan to a Cockpit
+
+The following command shows how to fetch information about the `premium` pricing plan and how to associate it with the Cockpit of your Scaleway default Project.
 
 ```hcl
 data "scaleway_cockpit_plan" "premium" {
@@ -18,6 +24,8 @@ resource "scaleway_cockpit" "main" {
 }
 ```
 
-## Arguments Reference
+## Argument reference
+
+This section lists the arguments that you can provide to the `scaleway_cockpit_plan` data source to filter and retrieve the desired plan.
 
-- `name` - (Required) The name of the plan.
+- `name` - (Required) Name of the pricing plan you want to retrieve information about.

docs/data-sources/domain_record.md

@@ -5,20 +5,28 @@ page_title: "Scaleway: scaleway_domain_record"
 
 # scaleway_domain_record
 
-Gets information about a domain record.
+The `scaleway_domain_record` data source is used to get information about an existing domain record.
 
-## Example Usage
+Refer to the Domains and DNS [product documentation](https://www.scaleway.com/en/docs/network/domains-and-dns/) and [API documentation](https://www.scaleway.com/en/developers/api/domains-and-dns/) for more information.
+
+
+## Query domain records
+
+The following commands allow you to:
+
+- query a domain record specified by the DNS zone (`domain.tld`), the record name (`www`), the record type (`A`), and the record content (`1.2.3.4`).
+- query a domain record specified by the DNS zone (`domain.tld`) and the unique record ID (`11111111-1111-1111-1111-111111111111`).
 
 ```hcl
-# Get record by name, type and data
+# Query record by DNS zone, record name, type and content
 data "scaleway_domain_record" "by_content" {
   dns_zone = "domain.tld"
   name     = "www"
   type     = "A"
   data     = "1.2.3.4"
 }
 
-# Get info by ID
+# Query record by DNS zone and record ID
 data "scaleway_domain_record" "by_id" {
   dns_zone  = "domain.tld"
   record_id = "11111111-1111-1111-1111-111111111111"
@@ -27,33 +35,31 @@ data "scaleway_domain_record" "by_id" {
 
 ## Argument Reference
 
-- `dns_zone` - (Optional) The IP address.
+This section lists the arguments that you can provide to the `scaleway_domain_record` data source to filter and retrieve the desired record:
+
+- `dns_zone` - (Optional) The DNS zone (domain) to which the record belongs. This is a required field in both examples above but is optional in the context of defining the data source.
 
-- `name` - (Required) The name of the record (can be an empty string for a root record).
-  Cannot be used with `record_id`.
+- `name` - (Required when not using `record_id`) The name of the record, which can be an empty string for a root record. Cannot be used with `record_id`.
 
-- `type` - (Required) The type of the record (`A`, `AAAA`, `MX`, `CNAME`, `DNAME`, `ALIAS`, `NS`, `PTR`, `SRV`, `TXT`, `TLSA`, or `CAA`).
-  Cannot be used with `record_id`.
+- `type` - (Required when not using `record_id`) The type of the record (`A`, `AAAA`, `MX`, `CNAME`, etc.). Cannot be used with `record_id`.
 
-- `data` - (Required) The content of the record (an IPv4 for an `A`, a string for a `TXT`...).
-  Cannot be used with `record_id`.
+- `data` - (Required when not using `record_id`) The content of the record (e.g., an IPv4 address for an `A` record or a string for a `TXT` record). Cannot be used with `record_id`.
 
-- `record_id` - (Optional) The record ID.
-  Cannot be used with `name`, `type` and `data`.
+- `record_id` - (Optional) The unique identifier of the record. Cannot be used with `name`, `type`, and `data`.
 
-- `project_id` - (Defaults to [provider](../index.md#project_id) `project_id`) The ID of the project the domain is associated with.
+- `project_id` - (Defaults to the Project ID specified in the [provider configuration](../index.md#project_id)). The ID of the Project associated with the domain.
 
 ## Attributes Reference
 
 In addition to all arguments above, the following attributes are exported:
 
-- `id` - The ID of the record.
+- `id` - The unique identifier of the record.
 
-~> **Important:** Domain records' IDs are of the form `{dns_zone}/{id}`, e.g. `subdomain.domain.tld/11111111-1111-1111-1111-111111111111`
+~> **Important:** Domain records' IDs are formatted as `{dns_zone}/{id}` (e.g. `subdomain.domain.tld/11111111-1111-1111-1111-111111111111`).
 
-- `ttl` - Time To Live of the record in seconds.
-- `priority` - The priority of the record (mostly used with an `MX` record)
-- `geo_ip` - Dynamic record base on user geolocalisation ([More information about dynamic records](../resources/domain_record.md#dynamic-records))
-- `http_service` - Dynamic record base on URL resolve ([More information about dynamic records](../resources/domain_record.md#dynamic-records))
-- `weighted` - Dynamic record base on IP weights ([More information about dynamic records](../resources/domain_record.md#dynamic-records))
-- `view` - Dynamic record based on the client’s (resolver) subnet ([More information about dynamic records](../resources/domain_record.md#dynamic-records))
+- `ttl` - The Time To Live (TTL) of the record in seconds.
+- `priority` - The priority of the record, mainly used with `MX` records.
+- `geo_ip` - Information about dynamic records based on user geolocation. [Find out more about dynamic records](../resources/domain_record.md#dynamic-records).
+- `http_service` - Information about dynamic records based on URL resolution. [Find out more about dynamic records](../resources/domain_record.md#dynamic-records).
+- `weighted` - Information about dynamic records based on IP weights. [Find out more about dynamic records](../resources/domain_record.md#dynamic-records).
+- `view` - Information about dynamic records based on the client’s (resolver) subnet. [Find out more about dynamic records](../resources/domain_record.md#dynamic-records).

docs/data-sources/domain_zone.md

@@ -5,10 +5,16 @@ page_title: "Scaleway: scaleway_domain_zone"
 
 # scaleway_domain_zone
 
-Gets information about a domain zone.
+The `scaleway_domain_zone` data source is used to get information about a DNS zone within a specific domain and subdomain in Scaleway Domains and DNS.
+
+Refer to the Domains and DNS [product documentation](https://www.scaleway.com/en/docs/network/domains-and-dns/) and [API documentation](https://www.scaleway.com/en/developers/api/domains-and-dns/) for more information.
 
 ## Example Usage
 
+### Query a domain zone
+
+The following command allows you to retrieve information about the DNS zone for the subdomain `test` within the domain `scaleway-terraform.com`.
+
 ```hcl
 # Get zone
 data "scaleway_domain_zone" "main" {
@@ -19,28 +25,29 @@ data "scaleway_domain_zone" "main" {
 
 ## Argument Reference
 
-The following arguments are supported:
+This section lists the arguments that you can provide to the `scaleway_domain_zone` data source to filter and retrieve the desired DNS zone:
+
 
-- `domain` - (Required) The domain where the DNS zone will be created.
+- `domain` - (Required) The primary domain name where the DNS zone is located. This is a mandatory field.
 
-- `subdomain` - (Required) The subdomain(zone name) to create in the domain.
+- `subdomain` - (Required) The subdomain (or zone name) within the primary domain. This is a mandatory field.
 
-- `project_id` - (Defaults to [provider](../index.md#project_id) `project_id`) The ID of the project the domain is associated with.
+- `project_id` - (Defaults to Project ID specified in [the provider configuration](../index.md#project_id)). The ID of the Scaleway Project associated with the domain. If not specified, it defaults to the `project_id` set in the provider configuration.
 
 ## Attributes Reference
 
 In addition to all arguments above, the following attributes are exported:
 
-- `id` - The ID of the zone, which is of the form `{subdomain}.{domain}`
+- `id` - The unique identifier of the zone, in the `{subdomain}.{domain}` format.
 
-- `ns` - NameServer list for zone.
+- `ns` - The list of name servers for the zone.
 
-- `ns_default` - NameServer default list for zone.
+- `ns_default` - The default list of name servers for the zone.
 
-- `ns_master` - NameServer master list for zone.
+- `ns_master` - The master list of name servers for the zone.
 
-- `status` - The domain zone status.
+- `status` - The status of the domain zone.
 
-- `message` - Message
+- `message` - Message associated with the domain zone (typically used for status or error messages).
 
-- `updated_at` - The date and time of the last update of the DNS zone.
+- `updated_at` - The date and time of the last update to the DNS zone.