diff --git a/roles/aws-cloud-watch-agent/README.md b/roles/aws-cloud-watch-agent/README.md
index 2ab46e4b..57fd5b19 100644
--- a/roles/aws-cloud-watch-agent/README.md
+++ b/roles/aws-cloud-watch-agent/README.md
@@ -1,16 +1,56 @@
+# AWS CloudWatch Agent
+
 This role installs the [AWS Cloud Watch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html).
+It is available for Ubuntu Linux running on AMD64 or ARM64 architectures.
+
+It does not configure or run the agent.
+Both of these actions should be performed in the [User Data](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-as-launchconfig.html#cfn-as-launchconfig-userdata) made available to EC2 instances.
+
+By default, this role will create metrics in the namespace `CWAgent`.
+It can be customised in [configuration](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html).
+
+The AWS documentation on CloudWatch Agent is fairly comprehensive, but scattered.
+For convenience, some relevant resources are listed below:
+
+- Creating the Cloud Watch configuration file:
+    - [Manually](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html)
+    - [Using the wizard](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file-wizard.html)
+- [Running the Cloud Watch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-common-scenarios.html)
+
+## Example configuration
+The following configuration will collect instance memory metrics. The metrics can be aggregated at the ASG level.
 
-Currently the role does not assume anything about how the agent should be configured, nor does the role run the agent.
-Typically both of these actions would be performed in the [User Data](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-as-launchconfig.html#cfn-as-launchconfig-userdata)
-made available to EC2 instances.
+```json
+{
+  "metrics": {
+    "append_dimensions": {
+      "InstanceId": "${aws:InstanceId}",
+      "AutoScalingGroupName":"${aws:AutoScalingGroupName}"
+    },
+    "aggregation_dimensions": [
+      ["AutoScalingGroupName"],
+      []
+    ],
+    "metrics_collected": {
+      "mem": {
+        "measurement": [
+          "available",
+          "total",
+          "used"
+        ]
+      }
+    }
+  }
+}
+```
 
-At the moment, the role is available for Ubuntu Linux running on AMD64 or ARM64 architectures.
+With this being the contents of the file `/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json` on an EC2 instance, we can add the following in the UserData to configure and start the agent:
 
-The AWS documentation on Cloud Watch agent is fairly comprehensive, but scattered; for convenience, some relevant
-resources are listed below:
+```bash
+amazon-cloudwatch-agent-ctl -a fetch-config -c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json
+amazon-cloudwatch-agent-ctl -a start
+```
 
-- creating the Cloud Watch configuration file:
-    - [manually](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html)
-    - [using the wizard](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file-wizard.html)
-- [running the Cloud Watch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-common-scenarios.html)
- 
\ No newline at end of file
+Some example PRs:
+- https://github.com/guardian/discussion-modtools/pull/866
+- https://github.com/guardian/deploy-tools-platform/pull/843
diff --git a/roles/cloudwatch-hardware-monitoring-cronjob/README.md b/roles/cloudwatch-hardware-monitoring-cronjob/README.md
index 749d6a78..d4438b44 100644
--- a/roles/cloudwatch-hardware-monitoring-cronjob/README.md
+++ b/roles/cloudwatch-hardware-monitoring-cronjob/README.md
@@ -1,8 +1,16 @@
 # CloudWatch hardware monitoring cronjob
 
+> [!WARNING]
+> DEPRECATED.
+> This role is uses IMDSv1 and therefore violates [FSBP EC2.8](https://docs.aws.amazon.com/securityhub/latest/userguide/ec2-controls.html#ec2-8).
+> For that reason, it's considered to be deprecated.
+> Please use [`aws-cloud-watch-agent`](../aws-cloud-watch-agent) instead.
+
 Utilises [mon-put-instance-data.pl](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/mon-scripts.html) script to 
 collect and report to CloudWatch memory, swap and disk space utilization data. 
 
+This role creates metrics in the namespace `System/Linux`.
+
 Requires the instance to have `cloudwatch:PutMetricData` (probably on resource `*`). 
 
 Example params: `monitor_memory_utilisation: true, monitor_disk_space_utilisation: true, paths: [/, /data]`
@@ -13,3 +21,5 @@ Example params: `monitor_memory_utilisation: true, monitor_disk_space_utilisatio
   path must be specified; else metrics won't be reported to CloudWatch
 - ensure that the EC2 instance on which the script is running has the correct permissions; as an example, see 
   [this](https://github.com/guardian/deploy-tools-platform/pull/114) PR
+- Be aware of differing CloudWatch metric namespaces when migrating to `aws-cloud-watch-agent`. 
+  You may want to use a custom namespace, or update your alarms and dashboard to use the new namespace.