Style improvements

Author: kbatuigas

modules/manage/pages/iceberg/iceberg-performance-tuning.adoc

@@ -12,7 +12,7 @@
 include::shared:partial$enterprise-license.adoc[]
 ====
 
-Use this guide to optimize the performance of Iceberg topics in Redpanda. It covers strategies for improving downstream query performance, tuning the Iceberg translation pipeline, and monitoring translation throughput.
+This guide covers strategies for optimizing the performance of Iceberg topics in Redpanda, including improving downstream query performance, tuning the Iceberg translation pipeline, and monitoring translation throughput.
 
 After reading this page, you will be able to:
 
@@ -22,7 +22,7 @@ After reading this page, you will be able to:
 
 == Prerequisites
 
-Before tuning Iceberg performance, you need to be familiar with how Iceberg topics work in Redpanda. See xref:manage:iceberg/about-iceberg-topics.adoc[About Iceberg Topics].
+You must be familiar with how Iceberg topics work in Redpanda. See xref:manage:iceberg/about-iceberg-topics.adoc[About Iceberg Topics].
 
 == Optimize query performance
 
@@ -32,7 +32,7 @@ Query engines read Parquet files from object storage to process Iceberg table da
 
 To improve query performance, consider implementing custom https://iceberg.apache.org/docs/nightly/partitioning/[partitioning^] for the Iceberg topic. Use the xref:reference:properties/topic-properties.adoc#redpanda-iceberg-partition-spec[`redpanda.iceberg.partition.spec`] topic property to define the partitioning scheme:
 
-[,bash,]
+[,bash]
 ----
 # Create new topic with five topic partitions, replication factor 3, and custom table partitioning for Iceberg
 rpk topic create <new-topic-name> -p5 -r3 -c redpanda.iceberg.mode=value_schema_id_prefix -c "redpanda.iceberg.partition.spec=(<partition-key1>, <partition-key2>, ...)"
@@ -50,7 +50,7 @@ To learn more about how partitioning schemes can affect query performance, and f
 
 [TIP]
 ====
-* Partition by columns that you frequently use in queries. Columns with relatively few unique values, also known as low cardinality, are also good candidates for partitioning.
+* Partition by columns that you frequently use in queries. Columns with relatively few unique values (low cardinality) are good candidates for partitioning.
 * If you must partition based on columns with high cardinality, for example timestamps, use Iceberg's available transforms such as extracting the year, month, or day to avoid creating too many partitions. Too many partitions can be detrimental to performance because more files need to be scanned and managed.
 ====
 

modules/manage/pages/iceberg/iceberg-topics-gcp-biglake.adoc

@@ -246,7 +246,7 @@ iceberg_dlq_table_suffix: _dlq
 +
 --
 * Replace `<bucket-name>` with your bucket name and `<gcp-project-id>` with your Google Cloud project ID.
-* You must set the `iceberg_dlq_table_suffix` property to a value that does not include dots or tildes (`~`). The example above uses `_dlq` as the suffix for the xref:manage:iceberg/iceberg-troubleshooting.adoc#dead-letter-queue-dlq[dead-letter queue (DLQ) table].
+* You must set the `iceberg_dlq_table_suffix` property to a value that does not include dots or tildes (`~`). The example above uses `_dlq` as the suffix for the xref:manage:iceberg/iceberg-troubleshooting.adoc#dead-letter-queue[dead-letter queue (DLQ) table].
 --
 +
 NOTE: If you edit `bootstrap.yml`, you can skip the cluster configuration step in <<configure-redpanda-for-iceberg>> and proceed to the next step in that section to enable Iceberg for a topic.
@@ -293,7 +293,7 @@ iceberg_dlq_table_suffix: _dlq
 +
 --
 * Replace `<bucket-name>` with your bucket name and `<gcp-project-id>` with your Google Cloud project ID.
-* You must set the `iceberg_dlq_table_suffix` property to a value that does not include dots or tildes (`~`). The example above uses `_dlq` as the suffix for the xref:manage:iceberg/iceberg-troubleshooting.adoc#dead-letter-queue-dlq[dead-letter queue (DLQ) table].
+* You must set the `iceberg_dlq_table_suffix` property to a value that does not include dots or tildes (`~`). The example above uses `_dlq` as the suffix for the xref:manage:iceberg/iceberg-troubleshooting.adoc#dead-letter-queue[dead-letter queue (DLQ) table].
 --
 
 ifndef::env-cloud[]

modules/manage/pages/iceberg/iceberg-troubleshooting.adoc

@@ -1,6 +1,10 @@
 = Troubleshoot Iceberg Topics
-:description: Diagnose and resolve errors in Redpanda Iceberg translation, including dead-letter queue inspection and record reprocessing.
+:description: Diagnose and resolve errors in Redpanda Iceberg translation, including dead-letter queue (DLQ) inspection and record reprocessing.
 :page-categories: Iceberg, Troubleshooting
+:page-topic-type: troubleshooting
+:personas: ops_admin, streaming_developer
+:learning-objective-1: Diagnose Iceberg translation errors using DLQ tables and metrics
+:learning-objective-2: Reprocess or drop invalid records from the DLQ table
 
 // tag::single-source[]
 
@@ -11,11 +15,16 @@ include::shared:partial$enterprise-license.adoc[]
 ====
 endif::[]
 
-This page covers how to diagnose and resolve errors that occur during Iceberg translation, including working with dead-letter queue (DLQ) tables and handling invalid records.
+{description}
 
-== Dead-letter queue (DLQ)
+Use this page to:
 
-If Redpanda encounters an error while writing a record to the Iceberg table, Redpanda by default writes the record to a separate dead-letter queue (DLQ) Iceberg table named `<topic-name>~dlq`. The following can cause errors to occur when translating records in the `value_schema_id_prefix` and `value_schema_latest` modes to the Iceberg table format:
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+
+== Dead-letter queue
+
+If Redpanda encounters an error while writing a record to the Iceberg table, Redpanda by default writes the record to a separate DLQ Iceberg table named `<topic-name>~dlq`. The following can cause errors to occur when translating records in the `value_schema_id_prefix` and `value_schema_latest` modes to the Iceberg table format:
 
 - Redpanda cannot find the embedded schema ID in the Schema Registry.
 - Redpanda fails to translate one or more schema data types to an Iceberg type.
@@ -62,7 +71,7 @@ The data is in binary format, and the first byte is not `0x00`, indicating that
 
 === Reprocess DLQ records
 
-You can apply a transformation and reprocess the record in your data lakehouse to the original Iceberg table. In this case, you have a JSON value represented as a UTF-8 binary. Depending on your query engine, you might need to decode the binary value first before extracting the JSON fields. Some engines may automatically decode the binary value for you:
+You can apply a transformation and reprocess the record in your data lakehouse to the original Iceberg table. In this case, you have a JSON value represented as a UTF-8 binary. Depending on your query engine, you might need to decode the binary value first before extracting the JSON fields. Some query engines decode the binary value automatically:
 
 .ClickHouse SQL example to reprocess DLQ record
 [,sql]
@@ -87,7 +96,7 @@ FROM (
 +---------+--------------+--------------------------+
 ----
 
-You can now insert the transformed record back into the main Iceberg table. Redpanda recommends employing a strategy for exactly-once processing to avoid duplicates when reprocessing records.
+You can now insert the transformed record back into the main Iceberg table. Redpanda recommends using an exactly-once processing strategy to avoid duplicates when reprocessing records.
 
 === Drop invalid records
 
@@ -102,8 +111,8 @@ endif::[]
 
 The following xref:reference:public-metrics-reference.adoc#iceberg-metrics[Iceberg metrics] help identify translation errors, invalid records, and catalog connectivity issues:
 
-* xref:reference:public-metrics-reference.adoc#redpanda_iceberg_translation_dlq_files_created[`redpanda_iceberg_translation_dlq_files_created`]: Number of dead letter queue (DLQ) Parquet files created. A non-zero and increasing value indicates records are failing to translate.
-* xref:reference:public-metrics-reference.adoc#redpanda_iceberg_translation_invalid_records[`redpanda_iceberg_translation_invalid_records`]: Number of invalid records encountered during translation, labeled by cause.
+* xref:reference:public-metrics-reference.adoc#redpanda_iceberg_translation_dlq_files_created[`redpanda_iceberg_translation_dlq_files_created`]: Number of DLQ Parquet files created. A non-zero and increasing value indicates records are failing to translate. See <<inspect-dlq-table>> to examine the failed records.
+* xref:reference:public-metrics-reference.adoc#redpanda_iceberg_translation_invalid_records[`redpanda_iceberg_translation_invalid_records`]: Number of invalid records encountered during translation, labeled by cause. See <<drop-invalid-records>> to configure how Redpanda handles these records.
 * xref:reference:public-metrics-reference.adoc#redpanda_iceberg_rest_client_num_commit_table_update_requests_failed[`redpanda_iceberg_rest_client_num_commit_table_update_requests_failed`]: Failed table commit requests to the REST catalog. Applies only when using a REST catalog (`iceberg_catalog_type: rest`). Persistent failures indicate catalog connectivity or permission issues.
 
 // end::single-source[]

modules/manage/pages/iceberg/specify-iceberg-schema.adoc

@@ -60,7 +60,7 @@ The following modes are compatible with producing to an Iceberg topic using Redp
 - `key_value`
 - Starting in version 25.2, `value_schema_latest` with a JSON schema
 
-Otherwise, records may fail to write to the Iceberg table and instead write to the xref:manage:iceberg/iceberg-troubleshooting.adoc#dead-letter-queue-dlq[dead-letter queue].
+Otherwise, records may fail to write to the Iceberg table and instead write to the xref:manage:iceberg/iceberg-troubleshooting.adoc#dead-letter-queue[dead-letter queue].
 ====
 
 == Configure Iceberg mode for a topic