Revamp best-practices landing page (#5127)

* Revamp best-practices landing page and fix section inconsistencies

The best-practices index only listed 7 of the section's 11 pages and gave no
framing for how they relate. Regroup the index into four intro'd sections
(namespace/tenancy/capacity, security, worker/workflow reliability,
organizational enablement), relocate multi-tenant-patterns.mdx into
best-practices/ where it's already tagged and cross-linked as belonging, and
copyedit managing-aps-limits.mdx, security-controls.mdx, managing-namespace.mdx,
and cloud-access-control.mdx for heading-case and word-choice consistency with
the rest of the section.

* Apply suggestion from @lennessyy

Co-authored-by: Lenny Chen <55669665+lennessyy@users.noreply.github.com>

---------

Co-authored-by: Lenny Chen <55669665+lennessyy@users.noreply.github.com>

Author: Duncanma

docs/best-practices/cloud-access-control.mdx

@@ -27,7 +27,7 @@ mechanics, see [Manage API keys](/cloud/api-keys) and [Manage service accounts](
 
 Related guidance:
 - [Namespace best practices](/best-practices/managing-namespace)
-- [Multi-tenant application patterns](/production-deployment/multi-tenant-patterns)
+- [Multi-tenant application patterns](/best-practices/multi-tenant-patterns)
 
 The high-level end-to-end rotation process is:
 
@@ -52,7 +52,7 @@ In the case that you are using multiple certificates signed by the same CA, and
 
 One convention is to give certificates a common name that matches the namespace. If you do this when using the same CA for dev and prod, then you can leverage Certificate Filters to prevent access to production environments. This is described in detail under the [authorization section](/cloud/certificates#control-authorization) of the documentation. 
 
-## Best practices
+## Recommendations
 
 ### Establish clear guidelines on authentication methods
 
@@ -96,7 +96,7 @@ The way you partition Namespaces should usually match the way you partition mach
   granular.
 
 For more on topology tradeoffs, see [Namespace best practices](/best-practices/managing-namespace) and
-[Multi-tenant application patterns](/production-deployment/multi-tenant-patterns).
+[Multi-tenant application patterns](/best-practices/multi-tenant-patterns).
 
 ### Rotate credentials without downtime
 

docs/best-practices/index.mdx

@@ -3,63 +3,75 @@ id: index
 title: Best practices
 sidebar_label: Best practices
 description:
-  Comprehensive best practices for working with Temporal, covering namespace management, security, and operational
-  excellence.
+  Prescriptive, validated guidance for platform teams and architects establishing Temporal standards, covering
+  namespace and tenancy design, Cloud security, Worker and Workflow reliability, and organizational enablement.
 toc_max_heading_level: 3
-hide_table_of_contents: true
+hide_table_of_contents: false
 keywords:
   - temporal best practices
   - operational excellence
   - security
   - namespace management
+  - multi-tenancy
+  - cost optimization
 tags:
   - Best Practices
 ---
 
-These guides outline foundational principles and best practices for using Temporal Cloud. It exists to provide a
-**validated, opinionated** framework that helps teams that either do not have an enablement plan for or want to evaluate
-and refine their use of Temporal.
+This section collects prescriptive, validated guidance for platform teams, architects, and developers establishing
+Temporal standards across an organization. Each page recommends a specific approach based on real-world deployments,
+rather than explaining how a feature works internally — for that, see [Encyclopedia](/temporal). Looking for a working
+code example instead of a principle? See [Guides](/guides) for pattern-by-pattern implementations with runnable code.
 
-## Overview
+## Namespace, tenancy, and capacity
 
-Without clearly defined Temporal standards, organizations often struggle with inconsistent Workflow implementations,
-fragmented best practices, and misaligned development approaches. This documentation framework helps developers
-establish robust Temporal standards by providing:
+Start here to decide how many Namespaces you need, how tenants share them, and what capacity model fits your traffic.
+These pages form one decision chain: draw your Namespace boundaries, decide how tenants share those boundaries, size
+your Actions-per-second capacity, and understand what it costs.
 
-- **Proven foundation principles** that have been validated across diverse use cases
-- **Standardized implementation patterns** for teams to adopt consistently across projects
-- **Confidence in alignment** with Temporal's architectural principles and recommended practices
+- **[Namespace best practices](./managing-namespace.mdx)** — naming conventions, organizational patterns for splitting
+  Namespaces, and production safeguards like deletion protection and Infrastructure as Code.
+- **[Multi-tenant application patterns](./multi-tenant-patterns.mdx)** — Task Queue and Namespace isolation patterns for
+  multi-tenant applications, with worked capacity-planning examples.
+- **[Managing Actions per Second (APS) limits](./managing-aps-limits.mdx)** — why workloads hit APS limits, how to
+  design Workflows that use Actions efficiently, and when to use Provisioned Capacity.
+- **[Cost optimization](./cost-optimization.mdx)** — common cost anti-patterns and strategies for reducing Actions and
+  Storage costs without sacrificing observability.
 
-By following this guidance, developers can define comprehensive Temporal standards that ensure their workflow
-orchestration implementations are maintainable, scalable, and aligned with platform best practices from the start.
+## Security and access control
 
-## Target audience
+Temporal Cloud secures the managed service; you're responsible for how your applications authenticate to it and who can
+administer your account. These two pages cover both halves.
 
-This section is intended for:
+- **[Managing Temporal Cloud access control](./cloud-access-control.mdx)** — choosing between mTLS certificates and API
+  keys, structuring Service Accounts, and rotating credentials without downtime.
+- **[Security controls for Temporal Cloud](./security-controls.mdx)** — identity and access management, network
+  isolation, data encryption, and availability guidance for a Temporal Cloud account.
 
-- Developers responsible for building a Temporal Cloud practice within their organization.
-- Anyone building tutorials, courses, onboarding paths, or documentation
-- Partners or vendors creating Temporal-related learning materials
+## Worker and Workflow reliability
 
-## Available guides
+These pages cover the full lifecycle of running reliable Workflows in production: deploy and tune Workers correctly,
+alert on the metrics that catch failures early, handle errors correctly in Workflow and Activity code, and validate
+that all of it survives real failure conditions before you rely on it.
 
-- **[Managing a Namespace](./managing-namespace.mdx)** Best practices for configuring, managing, and optimizing Temporal
-  Namespaces.
+- **[Worker deployment and performance](./worker.mdx)** — deployment, scaling, and tuning practices for Workers,
+  illustrated with a reference application.
+- **[Alerting on Worker metrics](./worker-alerting.mdx)** — a recommended alert set with thresholds and triage links.
+- **[Error handling](./error-handling.mdx)** — categorizing failures, when to mark errors non-retryable, and
+  implementing compensation with the Saga pattern.
+- **[Pre-production testing](./pre-production-testing.mdx)** — failure injection, load testing, and a game-day runbook
+  for validating operational readiness.
 
-- **[Managing Temporal Cloud Access Control](./cloud-access-control.mdx)** Guidelines for implementing proper access
-  control and user management in Temporal Cloud.
+## Organizational enablement
 
-- **[Security Controls for Temporal Cloud](./security-controls.mdx)** Comprehensive security practices for protecting
-  your Temporal Cloud deployment.
+Once your own standards are established, the next challenge is getting every team to follow them without funneling
+every question through the platform team.
 
-- **[Worker Deployment and Performance](./worker.mdx)** Best practices for deploying and optimizing Temporal Workers for
-  performance and reliability.
+- **[Knowledge hub](./knowledge-hub.mdx)** — what belongs in an internal Temporal knowledge hub, how to measure its
+  effectiveness, and how to keep it current.
 
-- **[Cost Optimization](./cost-optimization.mdx)** Strategies for optimizing costs associated with workloads running on
-  Temporal Cloud while maintaining Workflow reliability and observability.
-  
-- **[Pre-Production Testing](./pre-production-testing.mdx)** Experience-driven testing practices covering failure
-  injection, load testing, and operational validation.
-
-- **[Knowledge Hub](./knowledge-hub.mdx)** Best practices for building and maintaining an internal Temporal knowledge hub
-  that accelerates developer onboarding, reduces platform team support load, and establishes consistent standards.
+:::note Scope
+Most of this section covers Temporal Cloud operations. Namespace best practices, Worker deployment, and error handling
+apply to self-hosted Temporal too; security controls, access control, cost optimization, and APS limits are
+Cloud-specific. For self-hosted security guidance, see [Security (self-hosted)](/self-hosted-guide/security).
+:::