Skip to content

Trim the Getting Started guides and rename the StaticPage component - #20360

Draft
cnunciato wants to merge 13 commits into
masterfrom
cnunciato/onboarding-notes
Draft

Trim the Getting Started guides and rename the StaticPage component#20360
cnunciato wants to merge 13 commits into
masterfrom
cnunciato/onboarding-notes

Conversation

@cnunciato

@cnunciato cnunciato commented Jul 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What's here

Draft — work in progress.

A rework of the Get Started guides for all four clouds (AWS, Azure, GCP, Kubernetes), plus a couple of related component-docs improvements. The guides had grown text-heavy over time; this brings them back toward the tighter, higher-converting shape of the original 2020 flow — conveying the same information in a lighter package, keeping the simple static-website example (which feeds the component guide) and all the key pedagogy, while cutting noise.

Getting-started restructure (all four clouds)

  • Consistent 9-step flow. Split the crowded pages into their own steps so each page carries less: review-project and deploy-changes are now standalone, giving Install → Configure → Create → Review → Deploy → Modify → Deploy changes → Destroy → Next steps (matching the 2020 structure).
  • Per-step headings. Each step's H1 is its own heading (e.g. "Modify the program," "Deploy the stack") instead of a repeated "Get started with Pulumi and <Cloud>" banner; menu labels, titles, and H1s are aligned, and stepper buttons use linkTitle for short labels.
  • Tightened content. Collapsed redundant per-OS/per-command tabs into single blocks where the command doesn't actually differ; show the finished program once per language instead of building it up incrementally; dropped the "View on Pulumi Cloud" screenshot sections; rebuilt each next-steps down to the highest-value links; removed bold and other visual noise.
  • Removed the standalone create-component pages from Azure, GCP, and Kubernetes (AWS was done earlier) and connected each flow to the Build a Component guide instead. Old URLs are preserved via aliases.
  • Kept the code modern and correct. Presentation was tightened, but the programs still use current, correct APIs (not the deprecated inline forms shown in some older references). Kubernetes keeps its cloud-specific substance: the isMinikube config, the Deployment→Service arc, and the full service-access note (minikube tunnel / kubectl port-forward).

Component docs

  • Rename the sample StaticPage component to StaticWebsite. The component builds a static website, so StaticWebsite reads truer. Renames the class, args type, Go factory/package, Python module, resource token, and the visible instance name across all six sample-components-* programs, plus the matching example-program references and prose in build-a-component.md.
  • Collapse leading indentation in the guide's code snippets. Adds an opt-in dedent="true" parameter to the example-program shortcode that strips the whitespace common to every non-blank line of a quoted range, per the brand style guide's rule that quoted snippets omit the source's indentation. Applied to the component-source snippets in the guide.

Smaller polish

  • Tightened the shared first-run "sign in to Pulumi Cloud" note (cli-note).
  • Fixed a handful of pre-existing sample-output mismatches surfaced during the rework (e.g. an Azure static-endpoint hostname that didn't match its storage-account name; a Kubernetes destroy preview that still referenced the removed component wrapper).

Verification

  • make lint clean; every page renders 200; all Hugo shortcodes balanced.
  • Step weights are contiguous (2–10) with no collisions across all four clouds; moved/removed pages keep aliases so old URLs redirect rather than 404.
  • Rename: TypeScript type-checks (tsc --noEmit --skipLibCheck); Python and YAML parse; Go resolves the renamed internal package. The full pulumi preview program suite runs in CI.
  • Dedent: rendered locally and confirmed nested snippets (e.g. a constructor body) render flush-left while whole-file snippets keep their internal nesting.

🤖 Generated with Claude Code

cnunciato and others added 2 commits July 17, 2026 11:30
@cnunciato @claude
Update AWS get-started: second-person voice, add template explanation
df004e3 
- Replace first-person wording (we/our) with second-person (you/your)
- Add explanation that aws-typescript is a Pulumi template with links

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cnunciato @claude
Simplify AWS getting started flow and connect to component guide
011ec94 
- Remove create-component.md from getting started (link to guide instead)
- Update next-steps.md with components section linking to build-a-component guide
- Update build-a-component guide to use StaticWebsite naming (was StaticPage)
- Add connection between getting started and component guide in intro

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@pulumi-bot

pulumi-bot commented Jul 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Your site preview for commit fff2ad7 is ready! 🎉

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

@pulumi-bot

pulumi-bot commented Jul 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Lighthouse Performance Report

Commit: c6444b5 | Metric definitions

Page Device Score FCP LCP TBT CLS SI
Homepage Mobile 🟡 65 2.9s 3.5s 546ms 0.072 6.5s
Homepage Desktop 🟡 85 0.7s 1.4s 189ms 0.034 2.5s
Install Pulumi Mobile 🟡 57 7.9s 16.0s 2ms 0.000 7.9s
Install Pulumi Desktop 🟡 83 1.3s 1.8s 0ms 0.017 2.7s
AWS Get Started Mobile 🟡 59 5.9s 9.2s 0ms 0.086 5.9s
AWS Get Started Desktop 🟡 81 1.2s 2.1s 0ms 0.040 2.7s

@cnunciato cnunciato changed the title Simplify AWS getting started + rename sample component to StaticWebsite Trim the Started guides and rename the StaticPage component Jul 20, 2026
@cnunciato cnunciato changed the title Trim the Started guides and rename the StaticPage component Trim the Getting Started guides and rename the StaticPage component Jul 20, 2026
cnunciato and others added 11 commits July 19, 2026 17:43
@cnunciato @claude
Rename sample StaticPage component to StaticWebsite
1a9c10e 
The component builds a static website (S3 bucket + website config), so
"StaticWebsite" reads truer than "StaticPage". Renames the component
class, args type, Go factory (NewStaticWebsite) and package
(staticwebsitecomponent), Python module (static_website), resource token
(sample-components:index:StaticWebsite), and the visible instance name
(my-static-website) across all six sample-components-* programs, plus the
matching example-program references and prose in build-a-component.md.

Verified: TypeScript type-checks (tsc --noEmit --skipLibCheck), Python and
YAML parse, and Go resolves the renamed internal package. The full
pulumi-preview program suite runs in CI.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Collapse leading indentation in build-a-component code snippets
3e334b5 
Add an opt-in dedent="true" parameter to the example-program shortcode
that strips the leading whitespace common to every non-blank line of a
quoted range before highlighting, per the brand style guide's rule that
quoted snippets omit the source's indentation. A range already flush-left
(e.g. a whole class or function) is left untouched; a nested interior
(e.g. a constructor body) renders at column 0.

Apply it to the component-source snippets in the build-a-component guide
so nested quotes no longer carry two levels of source indentation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Remove create-component from Azure, GCP, and Kubernetes get-started
0aa19de 
Mirror the AWS getting-started simplification for the other three clouds:
drop the standalone "Create a component" page and point readers to the
Build a Component guide instead. For each cloud, delete create-component.md,
shift destroy-stack (8->7) and next-steps (9->8) weights up a slot, add a
"Create reusable components" section to next-steps linking to the guide,
and carry the removed page's canonical URL and aliases onto next-steps so
nothing 404s.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Simplify and restructure the AWS getting-started guide
d5d01a1 
Tighten the AWS get-started flow toward the leaner 2020 version without
changing its behavior: collapse the OS/language choosable noise, show the
finished program once in Modify the program, and trim redundant prose,
callouts, and next-steps links.

Make each step's H1 its own heading rather than the repeated "Get started
with Pulumi and AWS" banner, and keep menu names, titles, and H1s aligned.
Split the flow back into distinct Review the project and Deploy the changes
pages to match the 2020 structure, carrying the old URLs over as aliases so
nothing 404s.

Also polishes the shared get-started shortcodes (install body, install
note, auto-naming note, CLI note) used across all clouds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Refine AWS get-started copy and code comments
febfaa4 
Update the destroy-stack confirmation line, add a linkTitle so the stepper
button reads "Configure access," and drop trailing colons from label
comments in the modify-program code samples.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Simplify and restructure the Azure getting-started guide
77d241b 
Mirror the simplified AWS flow: split review-project and deploy-changes into
their own pages, apply the per-step H1 convention, tighten prose and collapse
redundant OS/command tabs, show the finished program once, strip the ESC note,
and rebuild next-steps. Fix a storage-account-name mismatch in the sample
output on deploy-changes and destroy-stack.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Simplify and restructure the GCP getting-started guide
ca21716 
Mirror the simplified AWS flow: split review-project and deploy-changes into
their own pages, apply the per-step H1 convention, tighten prose and collapse
redundant OS/command tabs, show the finished program once, strip the ESC note,
and rebuild next-steps. Align the url-helper note with AWS and drop a
redundant word from the next-steps description.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Simplify and restructure the Kubernetes getting-started guide
095e087 
Apply the simplified AWS structure to the Kubernetes flow: split
review-project and deploy-changes into their own pages, apply the per-step H1
convention, tighten prose, and rebuild next-steps while preserving the
Deployment-to-Service arc, the isMinikube config, and the service-access
guidance. Name the Go scaffold Deployment consistently and fix the landing
page title casing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Drop the redundant "Now you're ready to deploy!" line from review-pro…
c51cee2 
…ject

The stepper button already leads readers to the deploy step, so the line added
noise without information across all four clouds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Tighten the first-run Pulumi Cloud sign-in note
78d569b 
Co-Authored-By: Christian Nunciato <cnunciato@pulumi.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato @claude
Restore the full Minikube service-access note
fff2ad7 
Bring back the original two-option (minikube tunnel / port-forward) note
verbatim instead of the condensed version.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cnunciato
cnunciato force-pushed the cnunciato/onboarding-notes branch from 4971519 to fff2ad7 Compare July 20, 2026 00:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@cnunciato @pulumi-bot