gravitational · ptgott · Nov 11, 2024 · Oct 30, 2024
diff --git a/docs/pages/admin-guides/access-controls/access-request-plugins/datadog-hosted.mdx b/docs/pages/admin-guides/access-controls/access-request-plugins/datadog-hosted.mdx
@@ -3,8 +3,6 @@ title: Access Requests with Datadog Incident Management
 description: How to set up Teleport's Datadog Incident Management plugin for privilege elevation approvals.
 ---
 
-## How it works
-
 With Teleport's Datadog Incident Management integration, engineers can access the
 infrastructure they need to resolve incidents without longstanding admin
 permissions that can become a vector for attacks.
@@ -15,6 +13,15 @@ and approve or deny the requests via Teleport.
 
 This guide will explain how to set up Teleport's Access Request plugin for Datadog.
 
+## How it works
+
+The Teleport Datadog Incident Management integration connects to the Teleport
+gRPC API and listens for Role Access Requests. When the integration receives a
+status change for a Role Access Request, it either creates a new incident in
+Datadog or, if an incident exists, updates it. The integration also reads
+annotations on each Teleport Access Request and, depending on the annotations,
+may approve the Access Request automatically.
+
 ## Prerequisites
 
 (!docs/pages/includes/commercial-prereqs-tabs.mdx!)

diff --git a/...in-guides/access-controls/access-request-plugins/notification-routing-rules.mdx b/...in-guides/access-controls/access-request-plugins/notification-routing-rules.mdx
@@ -3,17 +3,23 @@ title: Routing Access Request notifications
 description: How to set up Teleport's Access Monitoring Rules to route Access Request notifications
 ---
 
+With Teleport's Access Monitoring Rules, Access Request notifications can be
+routed to plugins based on based on several conditions. For example, you may
+wish to send notifications to different Slack channels based on what roles or
+resources are being accessed, or based on what user is making the request.
+
 ## How it works
 
-With Teleport's Access Monitoring Rules, Access Request notifications
-can be routed to plugins based on based on several conditions.
-For example, you may wish to send notifications to different Slack channels
-based on what roles or resources are being accessed, or based on what user
-is making the request.
+The Access Monitoring Rule (AMR) is a dynamic Teleport resource that matches
+audit events with certain characteristics and instructs Teleport plugins to take
+action when it receives these events. Teleport plugins connect to the Teleport
+Auth Service and listen for AMRs. If an AMR matches the plugin, the plugin loads
+the the AMR and uses it to process incoming events. 
 
-Currently, only a subset of hosted plugins support notification routing rules.
-We are working on extending support to the rest of hosted plugins. Keep an eye
-on Teleport [changelog](../../../changelog.mdx) to learn about new plugins being added.
+Plugins implement AMR handling logic separately from one another. Currently,
+only a subset of hosted plugins support notification routing rules. We are
+working on extending support to the rest of hosted plugins. Keep an eye on
+Teleport [changelog](../../../changelog.mdx) to learn about new plugins.
 
 ## Prerequisites
 

diff --git a/docs/pages/admin-guides/access-controls/device-trust/device-management.mdx b/docs/pages/admin-guides/access-controls/device-trust/device-management.mdx
@@ -3,6 +3,10 @@ title: Manage Trusted Devices
 description: Learn how to manage Trusted Devices
 ---
 
+This guide provides instructions for performing Device Trust management
+operations, such as registering a trusted device, creating a device enrollment
+token, and removing a trusted device.
+
 ## Prerequisites
 
 (!docs/pages/includes/commercial-prereqs-tabs.mdx!)

diff --git a/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx b/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx
@@ -3,8 +3,6 @@ title: Hardware Key Support
 description: Hardware Key Support
 ---
 
-## Introduction
-
 <Admonition type="warning" title="Enterprise">
   Hardware Key Support requires Teleport Enterprise.
 </Admonition>

diff --git a/docs/pages/admin-guides/access-controls/idps/saml-guide.mdx b/docs/pages/admin-guides/access-controls/idps/saml-guide.mdx
@@ -4,10 +4,9 @@ description: How to configure and use Teleport as a SAML identity provider.
 h1: Teleport as a SAML identity provider
 ---
 
-## How to use Teleport as an identity provider
-
-This guide details an example on how to use Teleport as an identity provider to
-authenticate to external services.
+This guide details an example on how to use Teleport as a SAML identity provider
+(IdP). You can set up the Teleport SAML IdP to enable Teleport users to
+authenticate to external services through Teleport.
 
 ## Prerequisites
 
@@ -226,4 +225,4 @@ Next, add the role to your user.
 (!docs/pages/includes/add-role-to-user.mdx role="sp-manager"!)
 
 ## Next steps
-- Configure [SAML Attribute Mapping](./saml-attribute-mapping.mdx).
+- Configure [SAML Attribute Mapping](./saml-attribute-mapping.mdx).
diff --git a/docs/pages/admin-guides/deploy-a-cluster/multi-region-blueprint.mdx b/docs/pages/admin-guides/deploy-a-cluster/multi-region-blueprint.mdx
@@ -3,8 +3,6 @@ title: "Multi-region Blueprint"
 description: "Blueprint describing how to deploy a multi-region Teleport Enterprise cluster using CockroachDB."
 ---
 
-## Introduction
-
 This page describes how to deploy a Teleport cluster in multiple regions to
 improve resiliency and sustain regional failure. This is not a step-by-step
 guide but a blueprint on how to build a multi-region Teleport cluster. This

diff --git a/docs/pages/enroll-resources/database-access/auto-user-provisioning/mysql.mdx b/docs/pages/enroll-resources/database-access/auto-user-provisioning/mysql.mdx
@@ -3,6 +3,29 @@ title: MySQL Automatic User Provisioning
 description: Configure automatic user provisioning for MySQL.
 ---
 
+Teleport can automatically create an account in your MySQL database when a
+Teleport user connects to the database, removing the need for creating
+individual user accounts in advance or using the same set of shared database
+accounts for all users. This guide shows you how to set up automatic user
+provisioning for MySQL.
+
+## How it works
+
+Before enrolling a MySQL database with Teleport, you set up an admin user on the
+database with permissions to manage users. You then enroll the database in your
+Teleport cluster with a configuration field that includes the name of the admin
+user. 
+
+When a Teleport user connects to the database with a role that enables automatic
+user provisioning, the Teleport Database Service first connects to the database
+as the admin user, creates a temporary user in the database, then initiates a
+database session for the Teleport user as the temporary database user. 
+
+When the Teleport user closes the session, the Teleport Database Service
+prevents the temporary database user from accessing the database by, depending
+on the configuration, either removing the database user or disabling it and
+stripping its privileges.
+
 ## Prerequisites
 
 - Teleport cluster v14.1 or higher with a configured [self-hosted

diff --git a/docs/pages/enroll-resources/database-access/faq.mdx b/docs/pages/enroll-resources/database-access/faq.mdx
@@ -3,6 +3,10 @@ title: Database Access FAQ
 description: Frequently asked questions about Teleport database access.
 ---
 
+This page provides the answers to common questions about enrolling databases
+with Teleport. For a list of frequently asked questions about Teleport in
+general, see [Frequently Asked Questions](../../faq.mdx).
+
 ## Which database protocols does Teleport the Database Service support?
 
 The Teleport Database Service currently supports the following protocols:

diff --git a/docs/pages/enroll-resources/machine-id/faq.mdx b/docs/pages/enroll-resources/machine-id/faq.mdx
@@ -3,6 +3,10 @@ title: Machine ID FAQ
 description: Frequently asked questions about Teleport Machine ID
 ---
 
+This page provides answers to frequently asked questions about Machine ID. For a
+list of frequently asked questions about Teleport in general, see [Frequently
+Asked Questions](../../faq.mdx).
+
 ## Can Machine ID be used within CI/CD jobs?
 
 On CI/CD platforms where your workflow runs in an ephemeral environment (e.g

diff --git a/docs/pages/enroll-resources/machine-id/troubleshooting.mdx b/docs/pages/enroll-resources/machine-id/troubleshooting.mdx
@@ -3,6 +3,9 @@ title: Machine ID Troubleshooting Guide
 description: Troubleshooting common issues with Machine ID
 ---
 
+This page provides resolution steps for issues that you may come across when
+setting up Machine ID.
+
 ## A bot failed to renew a certificate due to a "generation mismatch"
 
 ### Symptoms

diff --git a/docs/pages/faq.mdx b/docs/pages/faq.mdx
@@ -4,6 +4,10 @@ description: Frequently Asked Questions About Using Teleport
 h1: Teleport FAQ
 ---
 
+This page includes answers to frequently asked questions about setting up,
+managing, and using Teleport. If you are new to Teleport, read our [Getting
+Started Guide](get-started.mdx).
+
 ## Can I use Teleport in production today?
 
 Teleport has been deployed on server clusters with thousands of hosts at

diff --git a/docs/pages/reference/agent-services/application-access.mdx b/docs/pages/reference/agent-services/application-access.mdx
@@ -3,6 +3,10 @@ title: Application Access Reference Documentation
 description: Configuration and CLI reference documentation for Teleport application access.
 ---
 
+This guide describes interfaces and options for interacting with the Teleport
+Application Service, including the static configuration file for the `teleport`
+binary, the dynamic `app` resource, and `tsh apps` commands.
+
 ## Configuration
 
 (!docs/pages/includes/backup-warning.mdx!)

diff --git a/docs/pages/reference/agent-services/database-access-reference/configuration.mdx b/docs/pages/reference/agent-services/database-access-reference/configuration.mdx
@@ -3,6 +3,9 @@ title: Database Access Configuration Reference
 description: Configuration reference for Teleport database access.
 ---
 
+This guide explains configuration options for the Teleport Database Service,
+which proxies user traffic between Teleport users and protected databases. 
+
 ## Database service configuration
 
 The following snippet shows full YAML configuration of a Database Service

diff --git a/docs/pages/reference/agent-services/database-access-reference/labels.mdx b/docs/pages/reference/agent-services/database-access-reference/labels.mdx
@@ -3,6 +3,9 @@ title: Database Labels Reference
 description: Database labels reference for Teleport database access.
 ---
 
+Teleport assigns system-defined labels to protected databases. This guide
+describes the system-defined labels and how Teleport uses them.
+
 ## Origin
 
 All registered databases have a predefined `teleport.dev/origin` label with one

diff --git a/docs/pages/reference/agent-services/desktop-access-reference/audit.mdx b/docs/pages/reference/agent-services/desktop-access-reference/audit.mdx
@@ -3,6 +3,12 @@ title: Desktop Access Audit Events Reference
 description: Audit events reference for Teleport desktop access.
 ---
 
+This guide lists the structures and field names of audit events related to
+connecting to remote desktops with Teleport. Use this guide to understand
+desktop-related audit events and configure your log management solutions if you
+are [exporting audit
+events](../../../admin-guides/management/export-audit-events/export-audit-events.mdx).
+
 ## windows.desktop.session.start (TDP00I/W)
 
 Emitted when a client successfully connects to a desktop or when a connection

diff --git a/docs/pages/reference/agent-services/kubernetes-application-discovery.mdx b/docs/pages/reference/agent-services/kubernetes-application-discovery.mdx
@@ -3,6 +3,11 @@ title: Kubernetes Application Discovery Reference
 description: This guide is a comprehensive reference of configuration options for automatically enrolling Kubernetes applications with Teleport.
 ---
 
+Kubernetes Application Discovery involves the Teleport Discovery Service,
+Teleport Application Service, and annotations on Kubernetes services. This guide
+shows you how to configure each of these to manage Kubernetes Application
+Discovery in your Kubernetes cluster.
+
 ## Configuring Teleport agent Helm chart
 
 You can configure scope of services discovery by setting value `kubernetesDiscovery` of the chart. For more information

diff --git a/docs/pages/reference/agent-services/okta.mdx b/docs/pages/reference/agent-services/okta.mdx
@@ -3,6 +3,10 @@ title: Okta Service Reference Documentation
 description: Configuration and CLI reference documentation for Teleport Okta service.
 ---
 
+This guide describes interfaces and options for configuring the Teleport Okta
+Service, including Okta import rules, Okta assignments, and `tctl` commands. It
+also includes troubleshooting instructions.
+
 ## Okta Import Rule resources
 
 Full YAML spec of Okta import rule resources managed by `tctl` resource commands:

diff --git a/docs/pages/reference/architecture/api-architecture.mdx b/docs/pages/reference/architecture/api-architecture.mdx
@@ -3,6 +3,12 @@ title: API Architecture
 description: Architectural overview of the Teleport gRPC API.
 ---
 
+This guide describes the architecture of the Teleport gRPC API, which enables
+clients like `tctl`, the Teleport Terraform provider, and the Teleport
+Kubernetes operator to manage dynamic resources in your Teleport cluster. If you
+are new to the Teleport gRPC API, read how to [Get
+Started](../../admin-guides/api/getting-started.mdx).
+
 ## Authentication
 
 The Auth API uses mTLS to authenticate a client-server connection. Therefore, the client must provide

diff --git a/docs/pages/reference/architecture/authentication.mdx b/docs/pages/reference/architecture/authentication.mdx
@@ -4,14 +4,13 @@ description: This chapter explains how Teleport uses certificate authorities to
 h1: Teleport Authentication with Certificates
 ---
 
-## Authentication
-
 Teleport handles both authentication and authorization.
 
 - Authentication is about proving an identity of a user or a service.
 - Authorization is proving access rights to something.
 
-This article covers authentication with short-lived certificates.
+This guide explains how Teleport handles authentication with short-lived
+certificates.
 
 ## Short-Lived Certificates
 

diff --git a/docs/pages/reference/architecture/authorization.mdx b/docs/pages/reference/architecture/authorization.mdx
@@ -4,14 +4,12 @@ description: This chapter explains how Teleport authorizes users and roles.
 h1: Teleport Authorization
 ---
 
-## Authorization
-
 Teleport handles both authentication and authorization.
 
 - Authentication is about proving an identity of a user or a service.
 - Authorization is proving access rights to something.
 
-This article covers authorization of users and services with RBAC.
+This article explains authorization of users and services with RBAC.
 
 ## Users and Roles
 

diff --git a/docs/pages/reference/architecture/teleport-cloud-architecture.mdx b/docs/pages/reference/architecture/teleport-cloud-architecture.mdx
@@ -3,6 +3,14 @@ title: Teleport Enterprise Cloud Architecture
 description: Cloud security, availability, and networking details.
 ---
 
+This guide describes architectural features of Teleport Enterprise (Cloud). In
+general, Teleport Enterprise (Cloud) includes managed deployments of the
+Teleport Auth Service and Teleport Proxy Service. Read on for information about
+topics like High Availability, deployment regions, and data retention.
+
+If you are new to Teleport Enterprise (Cloud), read the [Getting Started
+Guide](../../get-started.mdx).
+
 ## Security
 
 We have designed the Teleport Enterprise Cloud environment to be secure. We work with independent

diff --git a/docs/pages/reference/architecture/trustedclusters.mdx b/docs/pages/reference/architecture/trustedclusters.mdx
@@ -3,8 +3,6 @@ title: Trusted Clusters Architecture
 description: Deep dive into design of Teleport Trusted Clusters.
 ---
 
-## Overview
-
 Teleport can partition compute infrastructure into multiple clusters. A cluster
 is a group of Teleport connected resources. Each cluster
 manages a set of certificate authorities (CAs) for its users and resources.

diff --git a/docs/pages/reference/cloud-faq.mdx b/docs/pages/reference/cloud-faq.mdx
@@ -4,6 +4,10 @@ description: Teleport cloud frequently asked questions.
 tocDepth: 3
 ---
 
+This page provides answers to frequently asked questions about Teleport
+Enterprise (Cloud). For a list of frequently asked questions about Teleport in
+general, see [Frequently Asked Questions](../faq.mdx).
+
 ## Billing and usage
 
 ### How does Cloud Billing work?

diff --git a/docs/pages/reference/monitoring/tracing-service-configuration.mdx b/docs/pages/reference/monitoring/tracing-service-configuration.mdx
@@ -3,14 +3,14 @@ title: Distributed Tracing Configuration Reference
 description: Configuration reference for Distributed Tracing.
 ---
 
-## Tracing Service configuration
-
-`teleport.yaml` fields related to Distributed Tracing:
+This guide lays out the configuration fields that are related to distributed
+tracing in Teleport. You can find these fields in the Teleport configuration
+file, which is `teleport.yaml` by default:
 
 ```yaml
 # Main service responsible for Distributed Tracing.
 #
 # You must enable the Tracing Service once per teleport.yaml for all
 # agents that you wish to capture traces from,
 (!docs/pages/includes/diagnostics/tracing-config.yaml!)
-```
+```
diff --git a/docs/pages/reference/networking.mdx b/docs/pages/reference/networking.mdx
@@ -3,6 +3,14 @@ title: Networking
 description: This reference explains the networking requirements of a Teleport cluster, including its public address, ports, and support for HTTP CONNECT proxies.
 ---
 
+A Teleport cluster is a distributed system that may comprise a number of
+networks. On Teleport Enterprise (Cloud), for example, the Auth Service and
+Proxy Service run in Teleport-managed infrastructure, while Teleport users
+manage Agents and `tbot` instances.
+
+This reference guide describes the networking requirements of a Teleport
+cluster.
+
 ## Public address
 
 <Tabs>