Revise platform engineering content for clarity

[scottmparker]

Updated the content to enhance clarity and focus on self-service infrastructure capabilities. Revised key features, descriptions, and case studies for better alignment with platform engineering goals.

Proposed changes

Unreleased product version (optional)

Related issues (optional)

[claude]

Documentation Review

I've reviewed this PR for style, accuracy, and best practices. Overall, the changes improve clarity and focus on platform engineering use cases. However, I found several issues that need attention:

Critical Issues

1. Missing front matter field (Line 1)
The title field has been removed from the front matter. According to STYLE-GUIDE.md, every page must have exactly one H1 set in the front matter title field.

---
title: "Platform Engineering | Pulumi"
meta_desc: Build internal developer platforms that enable self-service infrastructure with policies and guardrails.

2. Missing newline at end of file (Line 224)
Per AGENTS.md, all Markdown files must end with a newline character.

Style & Clarity Issues

3. Inconsistent feature list structure (Lines 18-31)
The key_features_above section changed from detailed items with sub_title, description, image, button, and features to a simpler format. However, the field names don't match the template structure used elsewhere in the file. The new items use description, icon, and color but the template expects different fields based on the key_features section below.

4. Vague/unmeasurable claims (Line 31)
"Support 10x more teams" is a specific claim that may be difficult to substantiate. Consider rewording to avoid specific multipliers without data backing.

    - title: Scale without headcount
      description: |
        Support growing teams without proportionally growing your platform engineering org

5. Case studies section incomplete (Lines 201-222)
The case studies lost their link and logo fields, which are likely required by the template. Also missing the title field that was present in the original.

case_studies:
  title: Customers innovating with Pulumi Cloud
  items:
    - name: Atlassian
      link: /case-studies/atlassian/
      logo: atlassian
      description: Developers reduced their time spent on maintenance by 50%.

6. Missing period at end of sentence (Line 222)
The last case study description is missing a period:

      description: Built a multi-cloud, Kubernetes-based platform to standardize all deployments.

7. Stats section update (Lines 166-168)
The community and company statistics were updated significantly (10,000s → 150,000+, 1,000s → 3,000+). Please verify these numbers are current and accurate.

8. Removed CTA buttons
The original content had multiple "Try Pulumi Cloud for FREE" buttons with UTM tracking. These have been removed entirely. Verify this is intentional, as marketing content typically requires clear CTAs.

Minor Issues

9. Code example filename inconsistency (Lines 93, 103)

• Line 93: Program.cs
• Original used: MyStack.cs

Consider keeping consistent with existing examples unless there's a reason to change.

10. Code example filename inconsistency (Line 103)

• Line 103: App.java
• Original used: Main.Java

Note: The original had incorrect casing (Main.Java should be Main.java), so App.java is actually an improvement.

Recommendations

1. Add the missing title field to front matter
2. Restore the link, logo, and title fields to case studies section or verify the template supports the new structure
3. Add newline at end of file
4. Consider restoring CTAs with appropriate UTM tracking for marketing purposes
5. Verify statistical claims are current and accurate
6. Review template requirements for the key_features_above section to ensure the new structure will render correctly

---

Mention me (@claude) if you'd like me to review the updated version or help with any of these fixes.