Refresh what-is-pulumi for AEO: answer-first def, FAQ schema, entity table, SoftwareApplication opt-in - #20752
Refresh what-is-pulumi for AEO: answer-first def, FAQ schema, entity table, SoftwareApplication opt-in#20752workprentice[bot] wants to merge 2 commits into
Conversation
…table, SoftwareApplication opt-in Rewrites content/what-is/what-is-pulumi.md so the canonical Pulumi entity page leads with a 40-60 word answer-first definition naming the entity and category (Pulumi -> infrastructure as code platform) in the first sentence, adds a 5-row supporting-entity table, adds a Frequently Asked Questions section sourced from the actual GSC query shapes hitting this URL (which auto-qualifies for FAQPage schema, no template change needed), rewrites meta_desc to lead with the answer instead of marketing copy, switches the byline to the pulumi-content-team, and opts the page into a new software_application_schema front-matter flag. Also fixes a real schema gap in layouts/partials/schema/graph-builder.html: the SoftwareApplication node for the Pulumi Platform entity was only ever emitted on the homepage, so the one page whose entire job is defining that entity (this one) carried no SoftwareApplication markup at all. Hoists the shared fields into $softwareCore (mirroring the existing $orgDescription/$orgSameAs pattern) and gates a non-home emission on the new front-matter flag, deliberately excluding pricing/offers (which stay homepage-only) to avoid the kind of price-garbling risk flagged in prior schema work. Verified with a minimal isolated Hugo harness (the full repo's asset pipeline fails to build outside CI) that: homepage SoftwareApplication JSON-LD is byte-identical to before; what-is-pulumi now emits SoftwareApplication with 7 correct FAQ questions; an unrelated what-is page with no opt-in flag still emits no SoftwareApplication; and no two @graph nodes share an @id (the FAQPage/Article collision suspected going in does not actually exist in current code). Also verified (no change needed): Organization schema sameAs links all resolve correctly (GitHub, X/Twitter, YouTube, Wikidata, Wikipedia all 200; LinkedIn and Crunchbase 403/429 from anti-bot, not a defect). Interacts with #20595 (open, unmerged): that PR git-mv's content/what-is/*.md to content/resources/*.md and pins each article's URL via frontmatter so it does not change. The new software_application_schema flag lives in frontmatter (travels through a git mv) and the new else-branch gate keys off `not .IsHome`, which #20595 does not touch, so this change is rename-safe regardless of merge order.
|
@claude #new-review |
github-actions
Bot
added
review:triaging
Pre-merge Review — Last updated 2026-08-07T12:30:38ZTip Summary: This PR rewrites the opening of the Review confidence:
Investigation log
🔍 Verification trail36 claims extracted · 26 verified · 0 unverifiable · 1 contradicted · 2 framing-drift
🚨 Outstanding in this PRThese must be resolved or refuted before merging.
|
github-actions
Bot
added
review:outstanding-issues
github-actions
Bot
added
review:stale
|
Your site preview for commit e4c80f4 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-20752-e4c80f45.s3-website.us-west-2.amazonaws.com Changed pages: |
Lighthouse Performance ReportCommit: e4c80f4 | Metric definitions
|
2 participants
Summary
Refreshes
/what-is/what-is-pulumi/for AEO/entity clarity and closes a real SoftwareApplication schema gap. This is the primary deliverable for the "REFRESH: /what-is/what-is-pulumi + audit thin what-is pillars" board card.The card's premise was factually wrong — corrected here
The originating card claimed the
/what-is/section fell -27.1% WoW while/what-is/what-is-pulumiitself grew +25% WoW. Pulling the real Google Search Console numbers (propertysc-domain:pulumi.com, data through 2026-08-05):/what-is/what-is-pulumi/WoW: clicks 5 → 2 = -60% (not +25%). Impressions -10.8%.The real story is not a ranking problem, it's a CTR collapse at strong positions across the whole section — most
/what-is/pages sit at positions 5-20 with CTRs of 0.06%-0.3%, well below what those positions should earn. The headline data point: the query "what is pulumi" shows 478 impressions, 1 click, 0.21% CTR, at average position 1.94. Near-#1 and essentially no clicks — the answer is being consumed on the SERP (AI Overview / snippet) rather than clicked. That's the exact condition AEO content structure is meant to address: if the answer gets extracted anyway, make Pulumi's own canonical definition the thing that gets extracted.GSC also surfaces several LLM/agent-shaped queries hitting this exact URL ("evaluate the software development applications company pulumi on multi-cloud infrastructure management", "can pulumi's platform integrate with multiple cloud providers like aws, azure, and google cloud simultaneously?", etc.), all at 0 clicks — direct evidence AI systems already treat this URL as the Pulumi entity page. Those verbatim query shapes are the source for the new FAQ questions below.
Separately, Profound (AI citation tracking) shows pulumi.com is the #1 cited domain in "Infrastructure as Code" (9.96% citation share) but
/what-is/what-is-pulumi/does not appear among cited URLs at all — comparison pages carry the section's AI-citation load while the canonical brand-entity page earns zero. That's the gap this PR targets.Content changes (
content/what-is/what-is-pulumi.md)##/### ?headings auto-qualify what-is pages for FAQPage schema with no template change required.authors: ["pulumi-content-team"].software_application_schema: truefront matter flag (see template change below).Template change (
layouts/partials/schema/graph-builder.html)/what-is/what-is-pulumi/is the one page whose entire job is defining the Pulumi product entity, but the SoftwareApplication schema node was gated to.IsHomeonly — every non-home URL (including this one) carried Organization + WebSite + Article + Breadcrumb but no SoftwareApplication.Fix: hoisted the shared SoftwareApplication fields into a
$softwareCoredict above the.IsHomebranch (mirroring the repo's existing$orgDescription/$orgSameAspattern), then:$software := merge $softwareCore (dict "offers" ...)— verified byte-identical to the pre-change output.$softwareCore(plusurlandprogrammingLanguage, which do not touch the homepage node) only when.Params.software_application_schemais set. Deliberately excludesoffers/pricing — pricing stays homepage-and-/pricing/-only, to avoid the kind of price-garbling risk seen in prior schema work.content/what-is/what-is-pulumi.mdonly this cycle; not fanned out further.Verification
The full repo's
hugo buildfails locally on an unrelated asset-pipeline issue (compiledcss/bundle.css/css/marketing.cssand icon sprites aren't committed to the repo and are presumably produced by a separate CI/build step). Rather than skip verification, built a minimal isolated Hugo harness containing verbatim copies oflayouts/partials/schema/**and its actual dependencies, plus the realdata/team/team/*.toml,data/what_is_sections.yml, and the real content files, and rendered them directly. Confirmed:SoftwareApplicationJSON-LD is byte-identical before/after./what-is/what-is-pulumi/now emitsSoftwareApplication(nooffers) plusFAQPagewith all 7 questions parsed correctly.what-is-devops) still emits noSoftwareApplication— the gate isn't leaking.@graphnodes share an@idon any rendered page. I went in suspecting a#main-contentcollision between the Article and FAQPage nodes (faq-entity.htmlline 6 defaults@idto#main-content), butgraph-builder.htmlalready overwrites it viamerge $faqPage (dict "@id" "#faq")before appending to the graph — that defect does not exist; no fix was needed or made.Also verified (no change needed): all 8
Organization.sameAslinks resolve correctly — GitHub, X/Twitter, YouTube, Wikidata, and Wikipedia all return 200 (the Wikipedia article for Pulumi genuinely exists, pageid 74821952); LinkedIn (429) and Crunchbase (403) are anti-bot rate-limiting, not defects.Interaction with #20595
#20595 (open, unmerged) proposes moving
content/what-is/*.md→content/resources/*.mdviagit mv, with each article's URL pinned via a frontmatterurl:field so live URLs don't change, andtype: what-is→type: resources. This PR does not touch that migration and is designed to be rename-safe regardless of merge order: the newsoftware_application_schemaflag lives in frontmatter (travels through a cleangit mv), and the new schema gate keys offnot .IsHome, not.Typeor a content path, so it isn't affected by #20595's type/path rename. If #20595 merges first, this content edit should carry across via git's rename detection at merge/rebase time; if this merges first, #20595'sgit mvshould carry it forward untouched.🧠 This PR was created by workprentice.