content/docs/esc/concepts/environments.md links to /docs/iac/concepts/automation-api/
in two places when describing how Automation API manages a stack's imported ESC
environments — but that page has no ESC-environment coverage at all. The actual
addEnvironments/listEnvironments/removeEnvironment documentation, including
per-language examples, lives at /docs/esc/integrations/automation-api/. A reader
following either link lands on a page that doesn't answer the question that sent them
there.
Separately, the language-support matrix on
content/docs/esc/integrations/automation-api.md lists TypeScript/JavaScript, Python,
Go, and C#, but omits Java, even though the Java Automation API SDK
(com.pulumi.automation.WorkspaceStack) supports addEnvironments and
removeEnvironment (no list method, matching the .NET SDK's gap) and the page's own
narrative examples elsewhere in the docs already include a Java chooser tab for other
Automation API topics.
Finally, none of the narrative Automation API pages
(content/docs/iac/concepts/automation-api.md,
content/docs/iac/guides/building-extending/automation-api.md,
content/docs/iac/guides/building-extending/automation-api-advanced.md) cross-link to
the ESC integration page, so a reader who starts from the general Automation API docs
has no path to discovering the ESC-environment methods at all.
Proposed fix
- Fix the two misdirected links in
environments.md to point at
/docs/esc/integrations/automation-api/.
- Add Java to the language-support matrix and chooser on
content/docs/esc/integrations/automation-api.md, with a verified code example.
- Add short cross-references from the narrative Automation API pages to the ESC
integration page.
Supporting signal
GA4 shows /docs/iac/concepts/automation-api/ (the misdirected link target) has a
below-average engagement rate for its traffic volume, consistent with readers arriving,
not finding what they need, and leaving quickly.
content/docs/esc/concepts/environments.mdlinks to/docs/iac/concepts/automation-api/in two places when describing how Automation API manages a stack's imported ESC
environments — but that page has no ESC-environment coverage at all. The actual
addEnvironments/listEnvironments/removeEnvironmentdocumentation, includingper-language examples, lives at
/docs/esc/integrations/automation-api/. A readerfollowing either link lands on a page that doesn't answer the question that sent them
there.
Separately, the language-support matrix on
content/docs/esc/integrations/automation-api.mdlists TypeScript/JavaScript, Python,Go, and C#, but omits Java, even though the Java Automation API SDK
(
com.pulumi.automation.WorkspaceStack) supportsaddEnvironmentsandremoveEnvironment(no list method, matching the .NET SDK's gap) and the page's ownnarrative examples elsewhere in the docs already include a Java chooser tab for other
Automation API topics.
Finally, none of the narrative Automation API pages
(
content/docs/iac/concepts/automation-api.md,content/docs/iac/guides/building-extending/automation-api.md,content/docs/iac/guides/building-extending/automation-api-advanced.md) cross-link tothe ESC integration page, so a reader who starts from the general Automation API docs
has no path to discovering the ESC-environment methods at all.
Proposed fix
environments.mdto point at/docs/esc/integrations/automation-api/.content/docs/esc/integrations/automation-api.md, with a verified code example.integration page.
Supporting signal
GA4 shows
/docs/iac/concepts/automation-api/(the misdirected link target) has abelow-average engagement rate for its traffic volume, consistent with readers arriving,
not finding what they need, and leaving quickly.