Enhance policy documentation by adding description of policy as code (#16645)

* Enhance policy documentation by adding description of policy as code

Fixes #16609

* Improve policy as code documentation formatting

- Restructure sentence for better flow and readability
- Reformat benefits section as bulleted list for improved scannability
- Maintain 'Pulumi Policies brings' as singular per product naming

Co-authored-by: Cam Soper <[email protected]>

* Clarify usage of "Pulumi Policies" in documentation style guide

* Update meta description for clarity on policy as code in documentation

* Update content/docs/insights/policy/_index.md

Co-authored-by: Sara <[email protected]>

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Cam Soper <[email protected]>
Co-authored-by: Sara <[email protected]>

Author: 3 people

STYLE-GUIDE.md

@@ -205,11 +205,15 @@ See [Hugo diagrams docs](https://gohugo.io/content-management/diagrams/) and [Me
   - Pulumi ESC (Environments, Secrets, and Configuration)  
   - Pulumi IDP (Internal Developer Platform)  
   - Pulumi Insights  
-  - Pulumi Cloud  
+  - Pulumi Cloud
+  - Pulumi Policies  
 - Expand product acronyms at first mention. Use just the product name after.  
 - For non-Pulumi acronyms: spell out on first use, then use the acronym.  
   - Example: Virtual Private Cloud (VPC), then VPC.  
 - Widely known acronyms (API, HTTP, REST) don’t need expansion.
+- *Pulumi Policies* is the product name, so it's a singular proper noun (like "United States" or "Brooks Brothers").
+  - Always refer to it in the singular form (e.g., "Pulumi Policies enforces compliance").
+  - Never refer to it in the plural (e.g., avoid "Pulumi Policies enforce compliance").
 
 ---
 

content/docs/insights/policy/_index.md

@@ -1,7 +1,7 @@
 ---
 title: Policies
 title_tag: "Pulumi Policies | Insights & Governance"
-meta_desc: Enforce compliance and security policies across all cloud infrastructure with Pulumi Policies—for both IaC stacks and discovered resources.
+meta_desc: Enforce compliance and security across all cloud infrastructure using policy as code with Pulumi Policies—for both IaC stacks and discovered resources.
 h1: Policies
 meta_image: /images/docs/meta-images/docs-meta.png
 menu:
@@ -21,7 +21,25 @@ aliases:
   - /docs/insights/policy/core-concepts/
 ---
 
-Pulumi Policies empowers you to set guardrails to enforce compliance across your entire cloud infrastructure—whether resources are managed by Pulumi IaC, provisioned by other tools like Terraform or CloudFormation, or created manually. Using Pulumi Policies, you can write flexible business and security policies that protect your organization.
+Pulumi Policies enables you to implement policy as code across your entire cloud infrastructure. You define guardrails in code and apply them consistently across resources managed by Pulumi IaC, provisioned with Terraform or CloudFormation, or created manually. These codified business and security rules provide automated compliance protections for your organization.
+
+## What is policy as code?
+
+Policy as code applies software engineering practices to infrastructure policies. You write policies in programming languages and manage them alongside your infrastructure code, instead of manually configuring compliance rules through cloud provider consoles or maintaining policy documentation in wikis.
+
+This approach provides several key benefits:
+
+- **Cost control**: Define policies based on resource pricing to prevent expensive deployments before they happen. Set spending limits, identify unused resources, and enforce tagging for cost tracking and allocation across teams.
+
+- **Compliance and security**: Enforce guardrails that prevent common misconfigurations like public S3 buckets, exposed databases, or overly permissive security groups. Apply consistent security standards across development, staging, and production environments.
+
+- **Early validation**: Catch policy violations during `pulumi preview` before resources are created, not after deployment. This prevents non-compliant infrastructure from reaching production and reduces the time and cost of remediation.
+
+- **Best practices as code**: Encode organizational standards and cloud provider best practices as versioned, testable policies. Share policy packs across teams to ensure consistent infrastructure patterns throughout your organization.
+
+- **Integration with cloud-native tools**: Work alongside cloud provider features like AWS IAM Access Analyzer or AWS Organizations tag policies, combining Pulumi's policy enforcement with native cloud governance capabilities.
+
+Pulumi Policies brings these policy as code benefits to both Pulumi-managed infrastructure and resources discovered from other tools or created manually.
 
 {{% notes type="info" %}}
 Policy as Code is implemented via [analyzer plugins](/docs/iac/concepts/plugins/#analyzer-plugins), which are installed automatically with the Pulumi CLI.