Rewrite Pulumi vs. Terraform comparison page

[jkodroff]

Replace the marketing-style Terraform comparison with a neutral, feature-by-feature comparison.

Changes

• Rewrite content/docs/iac/comparisons/terraform/_index.md with sections for what each tool is, a comparison table, key differences, and adoption paths (coexistence, Pulumi Cloud as TF state backend, consuming TF providers and modules, conversion, import).
• Add reusable what-is-pulumi shortcode in HTML and markdown variants under layouts/shortcodes/.

[pulumi-bot]

Your site preview for commit 922dd3e is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-18704-922dd3e0.s3-website.us-west-2.amazonaws.com

[claude]

Docs review

The rewrite is a clear improvement — much cleaner structure, the feature table is genuinely scannable, and the adoption-paths section is the most concrete the page has been. Comments below focus on places where the "neutral" framing (per the PR description) slips back into the old marketing voice, plus a couple of factual nits.

Neutral framing slips

The PR's stated goal is to replace the marketing copy with a neutral comparison. A few phrases still read like positioning:

• content/docs/iac/comparisons/terraform/_index.md:30 — "ahead of it for Kubernetes and Azure" is a competitive claim, not a feature statement. The same point ("native providers generated from upstream API schemas, same-day coverage") is made factually in the table on line 41 and again in the "Provider and cloud coverage" paragraph on line 62, so this sentence can either be cut or de-editorialized:

  Pulumi's provider ecosystem covers the major hyperscalers and adds first-party native providers for [Kubernetes](/registry/packages/kubernetes/) and [Azure Native](/registry/packages/azure-native/) that are generated from upstream API schemas, so new resources and API versions land without waiting for a hand-authored release.
  

• content/docs/iac/comparisons/terraform/_index.md:40 — the Terraform side of the Language support row reads as commentary rather than a feature description: "a configuration-focused DSL whose syntax for control flow and dynamic blocks grows harder to read as project complexity increases". Suggest something like:

  | Language support | Python, TypeScript, JavaScript, Go, C#, Java, and YAML — general-purpose languages with familiar syntax for loops, conditionals, and abstractions | HashiCorp Configuration Language (HCL) — a declarative DSL with constructs for variables, conditionals, and iteration via `for_each`, `count`, and `dynamic` blocks |
  

• content/docs/iac/comparisons/terraform/_index.md:58 — "limited runtime logic, and reuse only through the module system" understates what HCL actually has (locals, for_each, count, dynamic blocks, conditional expressions, module composition). Consider tightening to something defensible:

  Terraform requires HCL, a domain-specific language designed for configuration. HCL is compact for small projects, but reuse is limited to its module system and there are no general-purpose programming abstractions like classes, inheritance, or third-party package ecosystems. Pulumi programs are written in general-purpose languages, so authors get loops, conditionals, classes, package management, IDE features (autocomplete, type checking, refactoring, go-to-definition), and the testing frameworks that already exist in those ecosystems. Pulumi also supports [YAML](/docs/iac/languages-sdks/yaml/) for users who prefer a markup format.
  

• content/docs/iac/comparisons/terraform/_index.md:70 — "values inside that state are still readable to anyone with access to the workspace" reads like a security swipe; HCP Terraform does have RBAC. A more neutral phrasing:

  Pulumi treats secrets as a first-class primitive. Values marked as secrets are encrypted in transit and at rest in the state file, anything derived from a secret is also encrypted, and each stack has its own encryption key. The default encryption provider can be replaced with [AWS KMS, Azure Key Vault, Google Cloud KMS, or HashiCorp Vault](/docs/iac/concepts/secrets/#available-encryption-providers). Terraform does not encrypt sensitive values inside the state file itself; the recommended approach is to integrate with HashiCorp Vault, a separate product. HCP Terraform encrypts state at rest, and workspace permissions control who can read sensitive values in that state.
  

Asymmetric treatment

• content/docs/iac/comparisons/terraform/_index.md:62 — "Provider and cloud coverage" opens with "Both tools have large provider ecosystems" but then only describes Pulumi. For balance, briefly characterize Terraform's side too (mature, large public registry, official + community providers) before pivoting to the native-provider point.

Factual / accuracy

• content/docs/iac/comparisons/terraform/_index.md:40, :58, and layouts/shortcodes/what-is-pulumi.html:1 / .markdown.md:1 — the language list drops F#, which is officially supported via the .NET SDK (see content/docs/iac/languages-sdks/dotnet/_index.md). Either include it or qualify with "and others (.NET supports F# and VB)".

• content/docs/iac/comparisons/terraform/_index.md:5 vs content/docs/iac/comparisons/terraform/_index.md:9 — the H1 is Pulumi vs. Terraform but the menu/breadcrumb title is still Terraform. Worth confirming this is intentional (it does match the sibling terminology page's pattern).

• Style guide note: STYLE-GUIDE.md lists the IaC product as "Pulumi IaC". The rewrite uses bare "Pulumi" throughout (title, h1, table headers, body). If this is a deliberate brand shift, no action needed; if not, the doc currently conflicts with the style guide.

Small structural notes

• :64-66 (Execution and orchestration) and :80-82 (Automation API) overlap heavily — both explain the Automation API and its use cases. Consider folding the Automation API into the Execution section, or trimming the Execution section to just CLI vs. remote runs and letting the Automation API section carry the SDK detail.

• :36 "Detailed comparison" and :54 "Key differences" are close synonyms; the table-vs-prose distinction isn't obvious from the headings. Renaming the first to "Feature comparison" (or "Comparison at a glance") would help readers anticipate what's coming.

Shortcode pairing

The HTML and markdown shortcodes (layouts/shortcodes/what-is-pulumi.html, layouts/shortcodes/what-is-pulumi.markdown.md) are semantically equivalent — good. Both are single-line files; left in place.

Links

Spot-checked the internal links — /docs/iac/concepts/pulumi-cloud/, /docs/iac/concepts/state-and-backends/, /docs/iac/automation-api/, /docs/iac/guides/migration/migrating-to-pulumi/from-terraform/ (and its #referencing-terraform-state and #converting-terraform-hcl-to-pulumi anchors), /docs/insights/policy/policy-packs/pre-built-packs/, /docs/iac/concepts/providers/#types-of-providers, /docs/iac/concepts/secrets/#available-encryption-providers, /docs/iac/get-started/terraform/terraform-state-backend/, /docs/iac/guides/building-extending/using-existing-tools/use-terraform-module/, and the Next steps URLs all resolve.

---

@claude — mention me if you'd like another pass after revisions, or want me to focus on a specific concern (e.g., further tightening the neutrality language, or proposing a consolidated Execution/Automation API section).

[pulumi-bot]

Lighthouse Performance Report

Commit: 922dd3e | Metric definitions

Page	Device	Score	FCP	LCP	TBT	CLS	SI
Homepage	Mobile	🔴 32	5.2s	6.4s	5395ms	0.010	6.6s
Homepage	Desktop	🟡 89	0.8s	1.0s	20ms	0.085	2.8s
Install Pulumi	Mobile	🔴 32	4.5s	6.0s	428ms	0.432	7.6s
Install Pulumi	Desktop	🟢 91	1.1s	1.5s	22ms	0.020	1.7s
AWS Get Started	Mobile	🟡 62	4.3s	5.9s	226ms	0.085	4.3s
AWS Get Started	Desktop	🟡 86	1.1s	1.5s	20ms	0.030	2.9s

[CamSoper]

Nice tightening of this page — the rewrite is much more skimmable than the marketing-heavy original, and every internal link checks out (verified the 17 doc paths and 4 anchors locally).

A few things I'd want to see before approving:

Language list — call it ".NET" rather than "C#"

The shortcode and the table cell list "Python, TypeScript, JavaScript, Go, C#, Java, and YAML". Pulumi's .NET SDK supports C#, F#, and VB — they all target the same MSIL, so the umbrella term ".NET" covers all three without making the bullet longer. The current wording reads as a regression vs. our own language docs (content/docs/iac/languages-sdks/dotnet/_index.md lists "C#, VB, F# (.NET)" in the title and menu name).

Affects:

• layouts/shortcodes/what-is-pulumi.html:1
• layouts/shortcodes/what-is-pulumi.markdown.md:1
• content/docs/iac/comparisons/terraform/_index.md:40

Neutrality vs. positioning

The PR description promises a "neutral, feature-by-feature comparison," but the page opens with "Pulumi's provider ecosystem is on par with Terraform's for the major hyperscalers and ahead of it for Kubernetes and Azure" (line 30). That's positioning, not neutral framing. Either soften the claim to fact-only ("Pulumi's Kubernetes and Azure Native providers are generated from upstream API schemas") or update the PR description to acknowledge the lens — both are fine, but the body and the description should match.

Selective native-provider call-out

The page names Kubernetes and Azure Native specifically, but AWS Native and Google Cloud Native also exist. Either include them or qualify why these two are highlighted (e.g. "the most mature schema-generated native providers"). As written, a reader could come away thinking only two clouds get native-provider treatment.

Em-dash density

17 em-dashes in 53 added lines is heavy enough that you might want to convert some to commas, parentheticals, or colons for rhythm. Not a blocker — just easier on the eye.

Happy to look at v2 whenever you're ready.

[jkodroff]

Pausing on this for now per @alexleventer's wishes because the page sees such heavy traffic. Will open PRs for other tools first.