content(what-is): expand the Internal Developer Platform explainer

[alexleventer]

Summary

Rewrites content/what-is/what-is-an-internal-developer-platform.md for AEO and SEO. Reorganizes the page around the canonical IDP questions, clarifies the relationship between IDPs and platform engineering / PaaS, and surfaces the practical build path.

What changed

• Opening definition — quotable one-sentence definition followed by a short lead-in clarifying that an IDP is the product a platform engineering team builds.
• Why organizations build IDPs — cognitive load, repeated patterns, standards on paper vs. in code, onboarding scale.
• What is inside an IDP — 9-row table covering catalog, self-service infra, environments, CI/CD, config/secrets, policy, observability, cost, docs.
• IDP vs. platform engineering vs. PaaS — explicit table to settle the terminology confusion (the discipline, the product, the rented platform).
• How to build one — six-step incremental path: painful path → product mindset → IaC substrate → policy as code → centralized secrets → portal/CLI → measure adoption.
• Benefits — delivery speed, onboarding, consistency, compliance, cognitive load, leverage.
• Pitfalls and anti-patterns — big-bang launches, treating it as infra not product, over-abstraction, mandate without value, portal-as-ticket-form, no escape hatch.
• Tooling table — 8 layers (portal, IaC, orchestration, CI/CD, config/secrets, policy, observability, identity).
• FAQ — 10 doubt-removers: simple definition, vs. platform engineering, small-team applicability, replacing infra teams, time to build, Backstage status, regulated industries, multi-cloud, vs. GitOps, Pulumi IDP fit.
• Cross-links — Platform engineering, IaC, DevOps, DevOps automation, configuration management, Pulumi IDP announcement blog.

Preserves the existing YouTube embed and allow_long_title frontmatter.

Test plan

• make serve; visit /what-is/what-is-an-internal-developer-platform/ and confirm rendering (incl. YouTube embed)
• Spot-check cross-links (/what-is/what-is-platform-engineering/, /product/internal-developer-platforms/, /blog/announcing-pulumi-idp/, /docs/insights/policy/, /product/esc/)
• CI lint + pinned review

🤖 Generated with Claude Code

[pulumi-bot]

Your site preview for commit a2fb7e6 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-19264-a2fb7e61.s3-website.us-west-2.amazonaws.com

[github-actions]

Pre-merge Review — Last updated 2026-05-20T16:53:46Z

Tip

Summary: This PR substantially expands content/what-is/what-is-an-internal-developer-platform.md (+141 / −74) into a comprehensive top-of-funnel explainer, parallel in structure to siblings like what-is-platform-engineering.md and what-is-infrastructure-as-code.md. For a what-is page that doubles as an IDP discovery landing, the kind of wrongness that blocks reader success is misrepresenting Pulumi's own product positioning — and two such findings did surface (Pulumi IDP is listed as a portal-tier peer to Backstage/Port/Cortex, and the supported-language list says "C#" where Pulumi's official branding is ".NET"). Investigative passes that ran: frontmatter sweep (clean), 38-claim extraction → 4-specialist verification (19 verified, 2 contradicted, 4 unverifiable), and Vale style scan. Hugo build was skipped (content-only PR — picked up by the full build in build-and-deploy.yml).

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	MEDIUM	Two contradicted findings about Pulumi-product framing need a fix; the four unverifiable bullets are best-practice generalizations rather than factual blockers, but a couple are worth softening.

Investigation log

• Cross-sibling reads: not run (not in a templated section)
• External claim verification: 19 of 38 claims verified (4 unverifiable, 2 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 30 Pass 1, 0 Pass 2, 8 Pass 3 (verified 5, contradicted 0, unverifiable 3).
• Cited-claim spot-checks: not run (no cited claims)
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: ran (recency words present in diff; spot-check in-review)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: not run (no fenced code blocks in content files)
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
2	14	0	0

🔍 Verification trail

38 claims extracted · 19 verified · 4 unverifiable · 2 contradicted

• L11 in content/what-is/what-is-an-internal-developer-platform.md "An Internal Developer Platform (IDP) is a self-service layer built on top of an organization's infrastructure, CI/CD, and operational tooling that lets applica…" → ✅ verified (evidence: The file at L11 contains exactly: "**An Internal Developer Platform (IDP) is a self-service layer built on top of an organization's infrastructure, CI/CD, and operational tooling that lets application developers provision environments, shi…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L11 in content/what-is/what-is-an-internal-developer-platform.md "An IDP abstracts the cloud, container, secrets, and policy stack behind a paved-road interface — a portal, a CLI, an API, or all three." → ➖ not-a-claim (evidence: The text at L11 is the PR author's own definitional description of what an IDP does ("It abstracts the cloud, container, secrets, and policy stack behind a paved-road interface — a portal, a CLI, an API, or all three"), not a third-party-a…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L13 in content/what-is/what-is-an-internal-developer-platform.md "An IDP is the product that a platform engineering team builds." → ✅ verified (framing: strengthened — source says "platform team ships to its developers"; claim says "platform engineering team builds" — both refer to the same concept; the source'…; evidence: The source page states: "An internal developer platform (IDP) is the product that a platform team ships to its developers." The claim's framing ("platform engineering team builds") is a close paraphrase of this.; source: content/what-is/what-is-platform-engineering.md)
• L42 in content/what-is/what-is-an-internal-developer-platform.md "Compliance baselines, security policies, and cost rules tend to live in PDFs and wiki pages until someone violates them. An IDP turns those standards into the…" → ➖ not-a-claim (evidence: The text is an editorial/positioning statement authored by the PR author describing the value proposition of an IDP (compliance standards becoming enforced defaults rather than PDFs/wikis). It is the author's own design narrative, not a th…; source: WebSearch ran query "internal developer platform compliance security policies enforcement by default"; claim is original editorial prose, not a falsifiable factual assertion.)
• L46 in content/what-is/what-is-an-internal-developer-platform.md "A new engineer who has to learn an organization's bespoke combination of cloud, Kubernetes, CI/CD, and policy before they can ship anything is a slow ramp. An…" → ➖ not-a-claim (evidence: The text at L46 is the PR author's own editorial prose describing the onboarding benefits of an IDP ("A new engineer who has to learn an organization's bespoke combination..."). It is a descriptive assertion authored by the PR writer thems…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L54 in content/what-is/what-is-an-internal-developer-platform.md "| Service catalog and templates | 'Golden paths' for common service shapes — REST API, worker, scheduled job, data pipeline. New services come from templat…" → ➖ not-a-claim (evidence: The text at L54 is a table row authored by the PR itself, describing what a "Service catalog and templates" component does in an IDP. It is the PR author's own explanatory prose, not an attribution to a third-party source or a falsifiable…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L58 in content/what-is/what-is-an-internal-developer-platform.md "Pulumi ESC and HashiCorp Vault are examples of central stores for hierarchical configuration and secrets in an IDP." → ✅ verified (evidence: The file at content/what-is/what-is-an-internal-developer-platform.md contains a table row stating: "Hierarchical configuration and secrets pulled at runtime from a central store like Pulumi ESC or HashiCorp Vault." This…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L59 in content/what-is/what-is-an-internal-developer-platform.md "| Security and policy guardrails | Policy as code blocks insecure configurations; encryption, IAM, and network defaults are baked…" → ✅ verified (evidence: The file content/docs/insights/policy/_index.md exists at the path /docs/insights/policy/ and its content directly covers "policy as code" for blocking insecure configurations: "Pulumi Policies enables you to implement policy as code a…; source: repo:content/docs/insights/policy/_index.md)
• L74 in content/what-is/what-is-an-internal-developer-platform.md "With a PaaS, developers consume the platform and nobody at the customer organization builds or operates it." → ➖ not-a-claim (evidence: The text at L74 is the PR author's own prose in the file being reviewed: "A vendor-operated platform like Heroku, Vercel, or Google App Engine. Developers consume it; nobody at the customer organization builds or operates it." This is the…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L74 in content/what-is/what-is-an-internal-developer-platform.md "Heroku, Vercel, and Google App Engine are examples of PaaS (Platform as a Service) offerings." → ✅ verified (framing: strengthened — Vercel is sometimes described more specifically as a frontend/serverless deployment platform rather than a general-purpose PaaS, but it is broad…; evidence: Multiple sources confirm all three as PaaS offerings: "Heroku is a fully managed PaaS" (GeeksforGeeks), "Google App Engine is a PaaS(Platform as a Service) by Google" (GeeksforGeeks), and Vercel is consistently listed alongside Heroku and…; source: WebSearch ran query "Heroku Vercel Google App Engine PaaS Platform as a Service examples")
• L76 in content/what-is/what-is-an-internal-developer-platform.md "With a PaaS, the platform is someone else's product; with an IDP, the platform is the organization's own product built by its platform engineering team." → ✅ verified (evidence: Multiple authoritative sources confirm this distinction. Humanitec states "one of the defining qualities of an IDP is that it's built and shipped as a product by a dedicated platform engineering team" and "you can't buy an IDP. But what yo…; source: https://humanitec.com/blog/wtf-internal-developer-platform-vs-internal-developer-portal-vs-paas; https://www.infoworld.com/article/2263059/what-is-an-internal-developer-platform-paas-done-your-way.html)
• L78 in content/what-is/what-is-an-internal-developer-platform.md "For more on the discipline that produces an IDP, see what is platform engineering?." → ✅ verified (evidence: The file content/what-is/what-is-platform-engineering.md exists in the repo with the title "What is Platform Engineering?" and covers the discipline that produces an IDP, confirming the internal link `/what-is/what-is-platform-engineerin…; source: repo:content/what-is/what-is-platform-engineering.md)
• L86 in content/what-is/what-is-an-internal-developer-platform.md "Identify the single workflow that consumes the most product-team time today — typically environment provisioning, deploying a new service, or onboarding a new…" → ➖ not-a-claim (evidence: The text at L86 is the PR author's own prescriptive guidance ("Start with the painful path") in a Pulumi-authored what-is article, not a third-party attributed assertion. It is editorial/advisory content describing the author's own recomme…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L94 in content/what-is/what-is-an-internal-developer-platform.md "The platform's 'Provision a new environment' button is, underneath, a Pulumi program." → ➖ not-a-claim (framing: This is a faithful description of the PR author's own design/pipeline (Pulumi's own product behavior), which per the verification rules is not a falsifiable th…; evidence: The statement "The platform's 'Provision a new environment' button is, underneath, a Pulumi program" appears verbatim in the PR's own file (content/what-is/what-is-an-internal-developer-platform.md, ~L94) as the PR author's description of…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L94 in content/what-is/what-is-an-internal-developer-platform.md "Pulumi components are used as reusable building blocks for platform components such as a Kubernetes namespace, a database, a CI/CD pipeline, and an observabili…" → ✅ verified (evidence: The IDP file at line ~94 states: "Every platform component (a Kubernetes namespace, a database, a CI/CD pipeline, an observability hookup) is a reusable Pulumi component that the platform composes on deman…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L98 in content/what-is/what-is-an-internal-developer-platform.md "Pulumi Policies and Open Policy Agent can block insecure configurations before they deploy." → ✅ verified (evidence: The /docs/insights/policy/ page confirms Pulumi Policies supports OPA (Rego) and has a "Preventative" enforcement mode: "Validates Pulumi stack resources during pulumi preview and pulumi up, blocking deployments when violations are d…; source: content/docs/insights/policy/_index.md)
• L102 in content/what-is/what-is-an-internal-developer-platform.md "Secrets in code, in CI logs, or in container images are a frequent breach pattern. The platform should pull secrets at runtime from a central store like [Pulum…" → 🤷 unverifiable (evidence: verification did not converge within 8 turns)
• L106 in content/what-is/what-is-an-internal-developer-platform.md "Backstage is a common tool used to build the web portal interface of an IDP." → ✅ verified (evidence: The official Backstage site (backstage.io) describes it as "an open source developer portal framework," and Spotify's own Backstage page states it is "an open framework for building internal developer portals (IDPs)" with over 3,000 compan…; source: https://backstage.io/ and https://backstage.spotify.com/learn/backstage-for-all/)
• L106 in content/what-is/what-is-an-internal-developer-platform.md "Most IDPs expose two interfaces: a web portal for discovery, requests, and visibility (often built on Backstage or Pulumi IDP), and a CLI or API for the actual…" → ➖ not-a-claim (evidence: The statement "Most IDPs expose two interfaces: a web portal for discovery, requests, and visibility (often built on Backstage or Pulumi IDP), and a CLI or API for the actual work" is the PR author's own editorial description of IDP archit…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L110 in content/what-is/what-is-an-internal-developer-platform.md "Track the percentage of services going through the paved road, lead time for a new environment, and qualitative developer satisfaction (typically with NPS-styl…" → ➖ not-a-claim (evidence: The text is the PR author's own editorial recommendation about IDP metrics and leading indicators — it is not attributed to any third-party source and is a faithful description of the author's own guidance/design within the document being…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L116-117 in content/what-is/what-is-an-internal-developer-platform.md "With a successfully rolled-out IDP, new engineers ship a real change in days, not months." → ➖ not-a-claim (evidence: The statement "new engineers ship a real change in days, not months" appears to be the PR author's own descriptive assertion about IDP benefits in their own documentation page, not a third-party-attributed factual claim or a citation to an…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L117 in content/what-is/what-is-an-internal-developer-platform.md "* Faster onboarding. New engineers ship a real change in days, not months." → ➖ not-a-claim (evidence: The line "New engineers ship a real change in days, not months" is an editorial assertion in the PR author's own "what-is" documentation content, not attributed to any third-party source. It is a descriptive benefit statement about IDPs wr…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L129 in content/what-is/what-is-an-internal-developer-platform.md "* Over-abstraction. Hiding the cloud completely from developers backfires the first time they need to debug a real production issue. The platform should be…" → ✅ verified (framing: strengthened — the claim is a specific, accurate synthesis of a broader industry consensus; no source contradicts it, and multiple authoritative sources confir…; evidence: The claim reflects a well-established IDP best-practice position found across multiple authoritative sources. Jellyfish's platform engineering guide warns that "a common pitfall is trying to build a platform that abstracts everything, crea…; source: WebSearch ran query "IDP paved road not a closed system platform engineering pitfalls"; top results: https://jellyfish.co/library/platform-engineering/best-practices/, https://www.infracloud.io/blogs/api-first-internal-developer-platforms/, https://www.infoworld.com/article/4073159/key-principles-of-a-successful-internal-developer-platform.html)
• L140-147 in content/what-is/what-is-an-internal-developer-platform.md "Pulumi ESC, HashiCorp Vault, and AWS Secrets Manager are representative tools for the configuration and secrets layer of an IDP." → 🤷 unverifiable (framing: narrowed — claim adds "AWS Secrets Manager" to the list, but the source only names "Pulumi ESC or HashiCorp Vault"; the source does not support the broader thr…; evidence: The what-is article's configuration-and-secrets table entry (around L140-147) mentions only "Pulumi ESC or HashiCorp Vault" as representative tools; AWS Secrets Manager does not appear in that section or in the /product/internal-developer-…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L144 in content/what-is/what-is-an-internal-developer-platform.md "| Configuration and secrets | Pulumi ESC, HashiCorp Vault, AWS Secrets Manager |" → ✅ verified (evidence: The file content/what-is/what-is-an-internal-developer-platform.md contains [Pulumi ESC](/product/esc/) in the "Configuration and secrets" row of the capabilities table, confirming the /product/esc/ URL is used as the link target for…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L145 in content/what-is/what-is-an-internal-developer-platform.md "| Policy as code | Pulumi Policies, Open Policy Agent, Kyverno |" → ✅ verified (evidence: The file content/docs/insights/policy/_index.md exists at the path /docs/insights/policy/ and is titled "Pulumi Policies | Insights & Governance", covering policy as code. The source page states: "Pulumi Policies enables you to impleme…; source: repo:content/docs/insights/policy/_index.md)
• L163 in content/what-is/what-is-an-internal-developer-platform.md "The IDP investment pays back once the number of product teams exceeds what a central group can support directly — typically somewhere in the dozens of engineer…" → 🤷 unverifiable (evidence: (escalated from pass1) No authoritative source confirms the specific framing that IDP investment pays back once product teams exceed what a central group can support "typically somewhere in the dozens of engineers." The source hint (/docs/…; source: WebSearch ran query "internal developer platform ROI team size threshold 'dozens of engineers'"; top results didn't address the claim's specific framing.; intuition: The source hint (/docs/iac/concepts/components/) is a Pulumi IaC page with no apparent connection to IDP ROI thresholds…)
• L171 in content/what-is/what-is-an-internal-developer-platform.md "The first useful slice of an IDP ships in weeks (e.g., a templated new-service workflow, a single paved-road CI/CD pipeline)." → ➖ not-a-claim (evidence: The statement "The first useful slice of an IDP ships in weeks (e.g., a templated new-service workflow, a single paved-road CI/CD pipeline)" is editorial guidance authored by the PR author in their own what-is article. It is a general best…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L175 in content/what-is/what-is-an-internal-developer-platform.md "Backstage is a developer portal — a UI layer — and is a common front-end for an IDP, but the platform itself is the combination of Backstage (or Port, Cortex,…" → ❌ contradicted (framing: shifted — the source positions Pulumi IDP as the full platform stack, not as a UI-layer portal front-end peer to Backstage/Port/Cortex; the claim incorrectly p…; evidence: The /product/internal-developer-platforms/ page positions Pulumi IDP as the full platform (IaC, policy, secrets, self-service, governance), not as a developer portal/UI-layer front-end. It lists Backstage as one interface option that int…; source: content/product/internal-developer-platforms.md (local repo file))
• L179 in content/what-is/what-is-an-internal-developer-platform.md "Compliance frameworks like SOC 2, HIPAA, and FedRAMP are easier to evidence when standards are enforced in code through policy as code and when every change le…" → ✅ verified (framing: strengthened — the source broadly covers compliance enforcement via policy as code; the claim narrows this to specific frameworks (SOC 2, HIPAA, FedRAMP) not e…; evidence: The /docs/insights/policy/ page confirms that policy as code provides "Compliance and security: Enforce guardrails that prevent common misconfigurations... Apply consistent security standards across development, staging, and production e…; source: content/docs/insights/policy/_index.md)
• L183 in content/what-is/what-is-an-internal-developer-platform.md "Pulumi is described as a multi-cloud-capable layer that abstracts cloud-specific differences behind shared components for AWS, Azure, GCP, or on-prem." → ✅ verified (framing: strengthened — claim narrows Pulumi's general multi-cloud abstraction capability to a specific "layer with shared components for AWS, Azure, GCP, or on-prem" f…; evidence: (escalated from pass1) Pulumi's official docs and product pages confirm it is a multi-cloud IaC platform supporting AWS, Azure, GCP, and on-prem (Kubernetes/on-premises), with Component Resources that "abstract away any cloud provider impl…; source: WebSearch ran query "pulumi.com what-is-infrastructure-as-code abstracts cloud-specific shared components AWS Azure GCP on-prem"; supporting evidence from https://www.pulumi.com/what-is/what-is-pulumi/ and https://www.pulumi.com/blog/multicloud-with-kubernetes-and-pulumi/)
• L187 in content/what-is/what-is-an-internal-developer-platform.md "GitOps is a workflow pattern where desired state is stored in Git and controllers reconcile the live system." → ➖ not-a-claim (evidence: The statement is the PR author's own explanatory description of GitOps within the article's body text — it is a faithful, standard characterization of the GitOps pattern (desired state in Git, controllers reconcile) consistent with the CNC…; source: repo:content/what-is/what-is-an-internal-developer-platform.md)
• L187 in content/what-is/what-is-an-internal-developer-platform.md "An IDP covers things GitOps doesn't, including templated service creation, environment provisioning, ticketless onboarding, and cost attribution." → 🤷 unverifiable (framing: shifted — the claim presents a specific four-item list as things "IDPs cover that GitOps doesn't"; sources confirm IDPs have these capabilities but don't frame…; evidence: Multiple sources confirm IDPs cover templated service creation, environment provisioning, and ticketless/self-service onboarding as IDP-specific capabilities. However, no authoritative source was found that frames these four items together…; source: WebSearch ran query "IDP internal developer platform vs GitOps differences templated service creation environment provisioning" and "IDP vs GitOps ticketless onboarding cost attribution differences"; top results didn't address the claim's exact comparative framing.)
• L191 in content/what-is/what-is-an-internal-developer-platform.md "The design intent of Pulumi IDP is described in the blog post 'Announcing Pulumi IDP' at /blog/announcing-pulumi-idp/." → ✅ verified (evidence: The blog post at content/blog/announcing-pulumi-idp/index.md exists in the repo with title "Announcing Pulumi IDP: Platform Engineering Accelerated" and describes the design intent: "Pulumi IDP is a bottom-up framework that integrates wi…; source: repo:content/blog/announcing-pulumi-idp/index.md)
• L191 in content/what-is/what-is-an-internal-developer-platform.md "Pulumi IDP allows platform teams to offer self-service infrastructure in TypeScript, Python, Go, C#, Java, or YAML without building everything from scratch." → ❌ contradicted (framing: shifted — source says ".NET" but claim says "C#"; these are different labels (C# is one language within .NET, but Pulumi's official branding uses ".NET"); evidence: The product page lists supported languages as "TypeScript, Python, Go, .NET, or Java" (plus YAML for low-code), not "C#". The claim substitutes "C#" for ".NET", which is a narrower/shifted term — Pulumi's IDP page consistently uses ".NET"…; source: repo:content/product/internal-developer-platforms.md — "Write infrastructure in TypeScript, Python, Go, .NET, or Java.")
• L195 in content/what-is/what-is-an-internal-developer-platform.md "Pulumi gives platform engineering teams infrastructure as code in real languages, reusable components, policy as code, configuration and secrets management, an…" → ✅ verified (evidence: The IDP page itself references all five capabilities attributed to Pulumi: IaC in real languages (TypeScript, Python, Go, C#, Java, YAML), reusable Pulumi components, policy as code via Pulumi Policies, configuration and secrets management…; source: content/what-is/what-is-an-internal-developer-platform.md and content/what-is/what-is-infrastructure-as-code.md)
• L199-204 in content/what-is/what-is-an-internal-developer-platform.md "The page cross-references the following internal pages: /what-is/what-is-platform-engineering/, /what-is/what-is-infrastructure-as-code/, /what-is/what-is-devo…" → ✅ verified (evidence: All 6 internal cross-references exist: /what-is/what-is-platform-engineering/, /what-is/what-is-infrastructure-as-code/, /what-is/what-is-devops/, /what-is/what-is-devops-automation/, /what-is/what-is-configuration-management/ al…; source: repo:content/what-is/what-is-an-internal-developer-platform.md; repo:content/what-is/what-is-devops.md; repo:content/what-is/what-is-devops-automation.md; repo:content/what-is/what-is-configuration-management.md; gh search code --owner pulumi "announcing-pulumi-idp" --repo pulumi/docs)
• L204 in content/what-is/what-is-an-internal-developer-platform.md "* Announcing Pulumi IDP" → ✅ verified (evidence: The blog post exists at content/blog/announcing-pulumi-idp/index.md with title "Announcing Pulumi IDP: Platform Engineering Accelerated", confirming the URL /blog/announcing-pulumi-idp/ resolves and the link text "Announcing Pulumi IDP…; source: repo:content/blog/announcing-pulumi-idp/index.md)

🚨 Outstanding in this PR

These must be resolved or refuted before merging.

• [L175] content/what-is/what-is-an-internal-developer-platform.md — Pulumi IDP is grouped with Backstage / Port / Cortex as if it were a portal-tier UI peer, but the Pulumi IDP product page positions Pulumi IDP as a full platform stack (IaC, components, policy, secrets, self-service interfaces — with a Backstage integration, not a peer relationship). Same miscategorization appears in the tools table at L140, where Pulumi IDP is listed under the "Platform portal" row alongside Backstage / Port / Cortex.

  Current (L175):

  Backstage is a developer portal — a UI layer. It's a common front-end for an IDP, but the platform itself is the combination of Backstage (or Port, Cortex, or Pulumi IDP) plus the automation, IaC, policy, secrets, and CI/CD that actually do the work.

  Suggested rewrite:

  Backstage is a developer portal — a UI layer. It's a common front-end for an IDP, but the platform itself is the combination of a portal (Backstage, Port, Cortex) plus the automation, IaC, policy, secrets, and CI/CD that actually do the work. Some products, like Pulumi IDP, bundle the IaC, components, policy, and self-service interfaces into a single platform (with a Backstage plugin for organizations that already standardize on Backstage).

  For the L140 table, either move Pulumi IDP out of the "Platform portal" row (e.g., into a "Platform / control plane" row or onto the "Infrastructure as code" row) or rename the row to reflect that Pulumi IDP covers more than the portal layer.

• [L191] content/what-is/what-is-an-internal-developer-platform.md — The supported-language list reads C#, but Pulumi's official branding (and the Pulumi IDP product page) uses .NET. C# is one language inside the .NET ecosystem; matching the product page's term avoids implying F#/VB are unsupported.

  Current (L191):

  Yes. Pulumi IDP provides templates, components, and a control plane built on Pulumi's infrastructure-as-code engine, so platform teams can offer self-service infrastructure in TypeScript, Python, Go, C#, Java, or YAML without building everything from scratch.

  Suggested rewrite (swap C# → .NET):

  Yes. Pulumi IDP provides templates, components, and a control plane built on Pulumi's infrastructure-as-code engine, so platform teams can offer self-service infrastructure in TypeScript, Python, Go, .NET, or Java (plus YAML for low-code patterns) without building everything from scratch.

⚠️ Low-confidence

Review each and resolve as appropriate — these don't block the PR.

• [L102] content/what-is/what-is-an-internal-developer-platform.md — "Secrets in code, in CI logs, or in container images are a frequent breach pattern." Widely-known security best-practice generalization rather than a falsifiable spec/price claim, so I'd keep it. Optional polish: link to a recognized source (the OWASP Top 10 / GitHub's secret-scanning research / a Verizon DBIR datapoint) if you want a one-shot citation behind "frequent breach pattern" — not a blocker.

• [L140-147] content/what-is/what-is-an-internal-developer-platform.md — "Configuration and secrets | Pulumi ESC, HashiCorp Vault, AWS Secrets Manager" — the verifier flagged AWS Secrets Manager as not appearing in the L58 prose row, but the L140 table is the broader "Representative tools" tour (where lists across rows correctly include vendor offerings beyond what the prose row spotlights — see GitHub Actions, GitLab CI, Argo CD, Buildkite on the CI/CD row for the same pattern). AWS Secrets Manager is widely-used and an appropriate representative example. Treat as resolved; no fix needed.

• [L163] content/what-is/what-is-an-internal-developer-platform.md — "The IDP investment pays back once the number of product teams exceeds what a central group can support directly — typically somewhere in the dozens of engineers." This is a soft heuristic, not a citable spec. It's defensible as written, but the precision of "dozens of engineers" implies a sourceable threshold that no authoritative source pins down. Author question: is this number derived from a Pulumi internal benchmark or platform-engineering research you can link? If not, consider softening to "… once a central group can no longer keep up with the volume of product-team requests — for most orgs, that's somewhere past the first handful of teams" or similar, without the specific headcount.

• [L187] content/what-is/what-is-an-internal-developer-platform.md — "the IDP also covers things GitOps doesn't (templated service creation, environment provisioning, ticketless onboarding, cost attribution)." The framing is editorially defensible — each item really is outside GitOps' "desired-state-reconciliation" scope — but no single source neatly stitches all four together that way, so a fact-checker can't verify the framing as a unit. Soften slightly to make it clear this is your synthesis, e.g., "…the IDP also covers scope GitOps wasn't designed for: templated service creation, environment provisioning, ticketless onboarding, and cost attribution." — not a blocker.

Style findings

Found by pattern-based linting; Findings may be false positives.

• line 13: [style] difficulty qualifier — Avoid difficulty qualifier 'easy' -- it judges difficulty for the reader (STYLE-GUIDE.md §Inclusive Language).
• line 34: [style] wordiness — 'all of' is too wordy.
• line 50: [style] filler — Don't start a sentence with 'There is'.
• line 64: [style] inclusive language — Avoid 'sanity check' (STYLE-GUIDE.md §Inclusive Language). Consider an alternative.
• line 70: [style] wordiness — 'it is' is too wordy.
• line 82: [style] filler — Don't start a sentence with 'There is'.
• line 120: [style] difficulty qualifier — Avoid difficulty qualifier 'just' -- it judges difficulty for the reader (STYLE-GUIDE.md §Inclusive Language).
• line 129: [style] weasel word — 'completely' is a weasel word!
• line 132: [style] difficulty qualifier — Avoid difficulty qualifier 'easy' -- it judges difficulty for the reader (STYLE-GUIDE.md §Inclusive Language).
• line 153: [style] difficulty qualifier — Avoid difficulty qualifier 'simple' -- it judges difficulty for the reader (STYLE-GUIDE.md §Inclusive Language).

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-05-20T16:53:46Z — Two Pulumi-product framing contradictions surfaced (Pulumi IDP miscategorized as a portal peer; language list says "C#" vs the official ".NET"); four unverifiable best-practice statements (none blockers); ten Vale style nags. (a2fb7e6)

---

Need a re-review? Want to dispute a finding? Mention @claude and include #update-review.
(For ad-hoc questions or fixes, just @claude — no hashtag.)