EDU-3861: Landing page prototype phase 2

- Adds inline definitions - Adds "under the hood" - Simplifies and focuses content - Adds explanatory images
temporalio · Feb 6, 2025 · 6f5accf · 6f5accf
1 parent cf6c2c1
commit 6f5accf
Show file tree

Hide file tree

Showing 11 changed files with 281 additions and 251 deletions.
diff --git a/docs/production-deployment/cloud/high-availability/best-practices.mdx b/docs/production-deployment/cloud/high-availability/best-practices.mdx
@@ -65,7 +65,7 @@ Trigger testing can:
 
 - **Assess recovery time**:
   Manual testing helps you measure actual recovery time.
-  You can check if it meets your expected Recovery Time Objective (RTO) of 20 minutes or less, as stated in the [High availability Namespace SLA](/cloud/high-availability#sla).
+  You can check if it meets your expected Recovery Time Objective (RTO) of 20 minutes or less, as stated in the [High availability Namespace SLA](/cloud/sla).
 
 - **Identify potential issues**:
   Failover testing uncovers problems not visible during normal operation.

diff --git a/docs/production-deployment/cloud/high-availability/enable.mdx b/docs/production-deployment/cloud/high-availability/enable.mdx
@@ -1,7 +1,7 @@
 ---
 id: enable
-title: Enable High Availability features
-sidebar_label: Enable high availability
+title: How to enable high availability
+sidebar_label: How to enable high availability
 slug: /cloud/high-availability/enable
 description: Temporal Cloud's High-Availability Namespaces offer automated failover, synchronized data replication, and high availability for workloads requiring disaster-tolerant deployment and 99.99% uptime. Use Global Namespace for self-hosted.
 tags:
@@ -22,105 +22,56 @@ keywords:
 
 import { RelatedReadContainer, RelatedReadItem } from '@site/src/components/related-read/RelatedRead';
 
-You enable High Availability features for a new or existing Namespace by adding a replica to the Namespace.
-When you add a replica, Temporal Cloud begins replicating ongoing and existing Workflows.
-Once the replication has completed and the replica is ready, your Namespace is ready for failover.
+Adding a replica to a new or existing Namespace enables Temporal Cloud's high availability features.
+You can either create a replica within the current region or deploy the replica to a different region.
+Once added, Temporal Cloud starts replicating ongoing and existing Workflows, along with their metadata.
+After replication is complete and your replica is ready, your Namespace is prepared for failover.
+If an incident occurs, failover transfers control from the active Namespace to the replica.
+
+This page shows you how to:
 
-- [Create a high availability Namespace](/cloud/high-availability/enable#create)
-- [Upgrade an existing Namespace to high availability functionality](/cloud/high-availability/enable#upgrade)
-- [Discontinuing high availability replicas](/cloud/high-availability/enable#discontinuing)
+- [Create a new high availability Namespace](/cloud/high-availability/enable#create)
+- [Upgrade an existing Namespace for high availability functionality](/cloud/high-availability/enable#upgrade)
+- [Discontinue high availability replication](/cloud/high-availability/enable#discontinuing)
 
 ## Create a high availability Namespace {#create}
 
-The following sections explain how to create a Namespace with a replica.
-You can create a replica within the current region or deploy the replica to a different region.
+To create a new replicated Namespace, you can use the Temporal Cloud Web site or the `tcld` command line utility.
+The following table explains how:
+
+| Approach                  | Instructions                                                                                                                                                  |
+|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Temporal&nbsp;Cloud&nbsp;Web&nbsp;UI**  | 1. Visit Temporal Cloud in your Web browser. <br /> 2. During Namespace creation, specify the active region for the Namespace. <br /> 3. Select "Add a replica". <ul><li>Adding a replica in the same region enables Replication.</li><li>Adding a replica in a different region enables Multi-region Replication.</li></ul> |
+| **Temporal&nbsp;`tcld`&nbsp;CLI**    | At the command line, enter: <br /> <tt>tcld namespace create \ <br /> &nbsp;&nbsp;&nbsp;&nbsp;--namespace \<namespace_id>.\<account_id> \ <br />&nbsp;&nbsp;&nbsp;&nbsp;--region \<active_region> \ <br /> &nbsp;&nbsp;&nbsp;&nbsp;--region \<replica_region></tt> <br /> <br /> Specify the [region codes](/cloud/service-availability) as arguments to the two `--region` flags. <ul> <li>Using the same region replicates to an isolation zone within that region.</li> <li>Using a different region within the same continent creates a multi-region Namespace.</li> </ul> Before pressing return, add your authentication credentials. For example, `--ca-certificate-file <path-to-pem-file>`. |
 
-::: note
+:::note
 
-While reading through this coverage, be aware that replication is not supported in all regions.
+Replication is not supported in all regions.
 For multi-region replication, pairing is limited to regions within the same continent.
 For more details, refer to ["Regional availability"].(/cloud/high-availabilityregional-availability).
 
 :::
 
-### Temporal Cloud Web UI
-
-Follow these steps to add replication to your Temporal Cloud Namespace:
-
-1. During Namespace creation, specify the first region for the Namespace.
-2. Select the “Add a replica” option.
-   Adding a replica in the same region enables Replication.
-   Adding a replica in a second region enables Multi-region Replication.
-
-### Temporal 'tcld' CLI
-
-Enter the following at the command-line to create a replicated Namespace:
-
-```sh
-tcld namespace create \
-   --namespace <namespace_id>.<account_id> \
-   --region <region> \
-   --region <region>
-```
-
-Specify the [region codes](/cloud/service-availability) as arguments to the two `--region` flags.
-
-- Using the same region replicates to an isolation zone within that region.
-- Using a different region within the same continent creates a multi-region Namespace.
-
-Before pressing return, add your authentication credentials.
-For example, `--ca-certificate-file <path-to-pem-file>`.
-
 ## Upgrade an existing Namespace to high availability functionality {#upgrade}
 
 Upgrade an existing single-region Namespace to high availability features by establishing a replica.
-The following sections explain how.
-You can either create a replica within the current region or deploy the replica to a different region.
-
-### Temporal Cloud Web UI
-
-Follow these steps to upgrade an existing Namespace:
-
-1. Visit Temporal Cloud Namespaces in your Web browser
-1. Navigate to the Namespace details page
-1. Select the “Add a replica” button.
-1. Choose either **Replication** (in the same region) or **Multi-region Replication** (across regions).
-   If you select Multi-region Replication, specify which region
-
-The web interface will present an estimated time for replication to complete.
-This time is based on your selection and the size and scale of the Workflows in your Namespace.
-An email alert is dispatched once your highly available Namespace is ready for use.
-
-### Temporal 'tcld' CLI
-
-Enter the following at the command-line to upgrade a Namespace for replication:
-
-```sh
-tcld namespace add-region \
-    --namespace <namespace_id>.<account_id> \
-    --region <region>
-```
-
-Specify the added [region code](/cloud/service-availability) as an argument to the `--region` flag.
-
-- Using the current region replicates to an isolation zone within your existing region.
-- Using a different region within the same continent creates a multi-region Namespace.
-
-Before pressing return, add your authentication credentials.
-For example, `--ca-certificate-file <path-to-pem-file>`.
+The following table explains how:
 
-An email alert is sent once your multi-region Namespace is ready for use.
+| Approach                  | Instructions                                                                                                                                                  |
+|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Temporal&nbsp;Cloud&nbsp;Web&nbsp;UI**  | 1. Visit Temporal Cloud Namespaces in your Web browser. <br /> 2. Navigate to the Namespace details page. <br /> 3. Select the “Add a replica” button. <br /> 4. Choose either **Replication** (in the same region) or **Multi-region Replication** (across regions). <ul><li>If you select Multi-region Replication, specify which region.</li></ul> The web interface will present an estimated time for replication to complete. <br /> This time is based on your selection and the size and scale of the Workflows in your Namespace. <br /> An email alert is dispatched once your highly available Namespace is ready for use. |
+| **Temporal&nbsp;`tcld`&nbsp;CLI**    | At the command line, enter: <br /> <tt>tcld namespace add-region \ <br /> &nbsp;&nbsp;&nbsp;&nbsp;--namespace \<namespace_id>.\<account_id> \ <br />&nbsp;&nbsp;&nbsp;&nbsp;--region \<replica_region></tt> <br /> <br /> Specify the added [region code](/cloud/service-availability) as an argument to the `--region` flag. <ul><li>Using the current region replicates to an isolation zone within your existing region.</li><li>Using a different region within the same continent creates a multi-region Namespace.</li></ul> <br /> Before pressing return, add your authentication credentials.<br />For example, `--ca-certificate-file <path-to-pem-file>`. <br /> An email alert is sent once your multi-region Namespace is ready for use. |
 
-## Discontinuing high availability replicas {#discontinuing}
+## Discontinue high availability replication {#discontinuing}
 
-Removing a Namespace replica removes the high availability and automatic failover features that provide Temporal's highest service level agreement.
-To disable these features and end charges:
+Removing a Namespace replica disables high availability and automatic failover features.
+Follow these steps to disable these features and end high availability charges:
 
 1. Navigate to the Namespace details page in Temporal Cloud.
-2. On the “Region” card, select the option to “Remove Replica”.
+2. On the "Region" card, select the option to "Remove Replica."
 
-The replica will be deleted and your Namespace will no longer be highly available.
-You will no longer be charged for this feature.
+Temporal Cloud deletes the replica.
+Your Namespace will no longer be highly available and you will no longer be charged for this feature.
 
 :::note
 

diff --git a/docs/production-deployment/cloud/high-availability/failovers.mdx b/docs/production-deployment/cloud/high-availability/failovers.mdx
@@ -1,7 +1,7 @@
 ---
 id: failovers
-title: failovers
-sidebar_label: Failovers
+title: How to trigger failovers
+sidebar_label: How to trigger failovers
 slug: /cloud/high-availability/failovers
 description: Temporal Cloud's High-Availability Namespaces offer automated failover, synchronized data replication, and high availability for workloads requiring disaster-tolerant deployment and 99.99% uptime. Use Global Namespace for self-hosted.
 tags:

diff --git a/docs/production-deployment/cloud/high-availability/faq.mdx b/docs/production-deployment/cloud/high-availability/faq.mdx
@@ -87,7 +87,7 @@ Temporal Cloud initiates failovers when there are incidents or outages in the cl
 This includes failures of databases, storage, etc.
 We trigger failovers any time we observe increased latencies or an increase in service errors that causes us to violate the SLA that is in our control.
 
-Read more about [automatic failovers](/cloud/high-availability/how-it-works#healthchecks).
+Read more about [automatic failovers](/cloud/high-availability/how-it-works#replication-lag).
 
 **Q: Are there any other types of failover not listed above?**
 
@@ -235,7 +235,7 @@ Not at the moment.
 
 Signals are cherry-picked during conflict resolution if there is replication lag and conflict. Workflows can theoretically revert multiple steps.
 
-Customers should decide whether to add logic to handle this or manually fix affected Workflows if they believe the risk is low. Other known limitations have been [documented](/cloud/high-availability/how-it-works#architecture) around causality and so forth.
+Customers should decide whether to add logic to handle this or manually fix affected Workflows if they believe the risk is low. Other known limitations have been [documented](/cloud/high-availability/how-it-works#workflow-execution-replication) around causality and so forth.
 
 **Q: How much time does it take to reconcile data after an incident is resolved? **