This document defines the canonical vocabulary for the kinds of content published on pulumi.com, and states who owns, who contributes to, and who consumes each type. Use these terms in nav headings, page titles, planning docs, and cross-team conversation.
The word "guides" currently refers to five different things:
- Docs uses "Guides" as a second-level nav heading inside several product sections (
content/docs/esc/guides/,content/docs/deployments/guides/,content/docs/idp/guides/all carrytitle: Guides;content/docs/iac/guides/holds the same kind of content but has no landing page of its own). - Marketing publishes pulumi.com/guides — "End-to-end blueprints for real cloud patterns" plus a library of Neo prompts. That page is not served from this repository.
- Marketing also publishes pulumi.com/tutorials, which are occasionally referred to as guides.
- The Registry currently republishes Pulumi examples and labels them "how-to guides".
- Historic docs URLs like
/docs/guides/...still circulate and are handled by redirects (scripts/redirects/).
This document disambiguates those terms, assigns an owner to every content type, and records the naming conflicts we still need to resolve. It complements, and does not replace:
AGENTS.md— file placement and agent workflow rulesSTYLE-GUIDE.md— prose and formatting rulesBLOGGING.md— blog-specific authoring rulesCONTRIBUTING.md— review pipeline and domain labels
Teams:
- Docs — the documentation team (
@pulumi/docsin the intended CODEOWNERS mapping). - Community Eng — developer relations and advocacy.
- Marketing — technical content marketing, product marketing, and growth.
- Eng/Product — product engineering and product management.
"Owns" means: sets the standards for the type, approves changes, and is accountable for accuracy and upkeep. "Contributes" means: routinely authors or supplies material, subject to the owner's review. "Consumes" describes the primary audience the type is written for.
Definition: Explanation-oriented documentation that builds a mental model — what a thing is, how it works, and why it's designed that way. Not tied to a specific task.
- Lives at:
content/docs/*/concepts/(e.g.content/docs/iac/concepts/,content/docs/esc/concepts/) - Examples: Stacks, State and backends
- Owns: Docs
- Contributes: Eng/Product (feature knowledge), Community Eng
- Consumes: Practitioners building an understanding of how Pulumi works
Definition: Walkthroughs that acquaint the reader with a product or feature. Sometimes that takes the form of a particular task ("build a component"), sometimes not ("organizing stacks," "composing environments"); best practices — advice on how to use the product well — also fall under this definition. What distinguishes a guide is how core it is to the product: if the thing being discussed is fundamental to Pulumi — something you need to know in order to use it — it's a guide; if it's about doing something with Pulumi that isn't core to the product (spinning up a specialized bit of infra, or integrating a third-party service the product has no direct integration with), it belongs elsewhere. Integrations the product supports directly — the VCS integrations, for example — are core, and their docs belong in guides. In short: guides in the docs are about understanding and using the product; tutorials are about doing stuff with the product. In the Diátaxis sense, a guide here can take the form of either a "how-to guide" or an "explanation" — both fit the needs of these sections.
- Lives at:
content/docs/iac/guides/,content/docs/esc/guides/,content/docs/deployments/guides/,content/docs/idp/guides/ - Examples: Migrating from Terraform, ESC + GitHub Actions integration guides
- Owns: Docs
- Contributes: Eng/Product, Community Eng, community
- Consumes: Practitioners new to Pulumi or seeking help with (or a better understanding of) a particular product or feature
Definition: Task-oriented, sequenced, hands-on lessons. The reader follows along end to end and comes out having built something and learned Pulumi. Tutorials sometimes have time estimates and are occasionally grouped into collections and multi-part modules.
- Lives at:
content/tutorials/→ pulumi.com/tutorials (also aliased at/learn) andcontent/docs/*/get-started - Examples: IaC Get Started, Deployments Get Started, ESC Get Started, Pulumi Fundamentals (3-part module), "Importing AWS Infrastructure"
- Owns: Marketing
- Contributes: Docs, Eng/Product
- Consumes: Newcomers and learners
Getting Started (content/docs/{iac,deployments,esc}/get-started/) are the only tutorials that currently live within the docs. They're tutorials because they're end-to-end onboarding paths — hyperfocused on getting up and running with one aspect of Pulumi — and because they're owned, maintained, and measured by Marketing. We'll aim to call them the Getting Started tutorials (that's what they are in the Diátaxis sense), even though the word "guides" has stuck to them historically. Discovery and IDP don't currently have one, but probably should.
Definition: Lookup material — exhaustive, structured, factual. Optimized for finding one precise answer, not for reading front to back.
- Lives at:
content/docs/reference/, generated CLI docs (content/docs/iac/cli/commands/,content/docs/esc/cli/commands/), SDK/API reference, and the Pulumi Registry (published from its own pipeline) - Examples:
pulumi upCLI reference, Pulumi Python SDK API Reference - Owns: Docs (hand-written pages); Eng/Product (generated content — CLI command docs are auto-generated; the CODEOWNERS carve-out that would let them merge without docs review is currently commented out, like the rest of that file)
- Contributes: Eng/Product
- Consumes: Practitioners who know what they're looking for
Definition: End-to-end, outcome-framed patterns for a complete real-world scenario ("Build a Cloud Landing Zone," "HIPAA-Compliant Infrastructure on AWS"), packaged to show what Pulumi can do — including Neo prompt libraries. Part sales asset, part architecture pattern; the page describes them as "end-to-end blueprints for real cloud patterns."
- Lives at: pulumi.com/guides — not in this repository; published from a separate marketing pipeline
- Owns: Marketing
- Contributes: Community Eng, Eng/Product (technical validation)
- Consumes: Evaluators and buyers scoping a solution
Status: effectively end-of-life. This content is being folded selectively into Tutorials. Going forward, "Guides" refers only to the docs guides above — see Naming decisions.
Definition: Educational pages or topic clusters answering a definitional search query ("What is GitOps?"). Product-light, concept-heavy.
- Lives at:
content/what-is/(section title: "Cloud Engineering Concepts Explained") - Owns: Marketing
- Contributes: Docs, Community Eng
- Consumes: Evaluators early in research
Definition: Point-in-time announcements, engineering stories, and opinion. Blog posts are historical records: per AGENTS.md, they are not kept current — broken links get routed around, and revisions are the exception (stamped with updated:).
- Lives at:
content/blog/ - Owns: Marketing. Individual blog authors own the accuracy of their content at time of publishing. Marketing owns the rest, including design, editorial, and amplification.
- Contributes: Everyone — Eng/Product, Community Eng, Docs, Marketing, guest authors
- Consumes: Community, customers, news readers
Definition: Customer success narratives — who they are, what problem they had, how Pulumi solved it, with quotes and metrics.
- Lives at:
content/case-studies/ - Owns: Marketing
- Contributes: Sales/CS (customer relationships), Community Eng
- Consumes: Buyers seeking social proof
Definition: Template-driven pages that sell — product pages, solution pages, pricing, comparison/topic landing pages, and ad-campaign landing pages.
- Lives at:
content/product/,content/solutions/,content/topics/,content/pricing/,content/why-pulumi/,content/gads/, and ~20 similar campaign directories - Owns: Marketing
- Contributes: Eng/Product (feature accuracy), Docs (technical review)
- Consumes: Evaluators and buyers
Definition: Registration and recap pages for webinars, workshops, and conference presence.
- Lives at:
content/events/ - Owns: Marketing and Community Eng, jointly (Marketing owns promotion and pages; Community Eng owns technical content delivered)
- Consumes: Community members and prospects
Definition: Dated records of what shipped — one changelog entry per change, plus launch pages.
- Lives at:
content/releases/,content/releases/changelog/ - Owns: Marketing
- Contributes: Eng/Product, Docs, Community Eng
- Consumes: Existing and prospective users tracking product evolution
Definition: Starter kits for generating new Pulumi projects with pulumi new.
- Lives at:
content/templates/(sourced from https://github.com/pulumi/templates); includes both starter and architecture templates. - Owns: Marketing
- Contributes: Eng/Product, Community Eng
- Consumes: Practitioners bootstrapping new projects
Definition: Testable programs designed for embedding into docs and tutorials.
- Lives at:
static/programs/, tested viascripts/programs/test.sh - Owns: Docs
- Contributes: Eng/Product, Marketing, Community Eng
- Consumes: Practitioners engaging with the docs. Every docs page that embeds an example should ideally use one of these programs.
| Type | One-line definition | Lives at | Owns | Contributes | Consumes |
|---|---|---|---|---|---|
| Conceptual docs | Explains how Pulumi works and why | content/docs/*/concepts/ |
Docs | Eng/Product, Community Eng | Practitioners |
| Guides | Walkthroughs designed for understanding and using Pulumi | content/docs/*/guides/ |
Docs | Eng/Product, Community Eng, community | Practitioners |
| Tutorials | Sequenced hands-on learning | content/tutorials/ |
Marketing | Docs, Eng/Product | Newcomers, learners |
| Reference | Exhaustive lookup material | content/docs/reference/, generated CLI docs |
Docs + Eng/Product | Eng/Product | Practitioners |
| Topics | Adjacent, industry-relevant educational content ("what is X") | content/what-is/ |
Marketing | Docs, Community Eng | Learners, evaluators |
| Blog posts | Point-in-time posts; historical | content/blog/ |
Marketing | Everyone | Community |
| Case studies | Customer success stories | content/case-studies/ |
Marketing | Sales/CS, Community Eng | Buyers |
| Product/campaign pages | Pages that sell | content/product/, solutions/, gads/, … |
Marketing | Eng/Product, Docs | Evaluators, buyers |
| Events & workshops | Registration/recap pages | content/events/ |
Marketing + Community Eng | — | Community, prospects |
| Releases & changelog | Dated record of what shipped | content/releases/ |
Marketing | Eng/Product, Docs | Existing and prospective users |
| Templates | Runnable starting points | content/templates/ |
Marketing | Eng/Product, Community Eng | Practitioners |
| Example programs | Tested, embeddable code | static/programs/ |
Docs | Eng/Product, Community Eng | Practitioners |
The "guides" collision described at the top of this document has been resolved as follows (agreed in PR #20803):
- "Guides" refers only to the docs guides — the ones that live in the docs, generally underneath a given product or feature. These are owned by the Docs team, and each one, in the Diátaxis sense, can take the form of either a "how-to guide" or an "explanation." These are the only things we'll refer to as Guides going forward.
- "Tutorials" refers to either:
- The things we currently call "the Getting Started guides" (
content/docs/*/get-started/). We'll try to call these the Getting Started tutorials going forward — that's what they are in the Diátaxis sense. - The things that live at pulumi.com/tutorials. The content at pulumi.com/guides is being folded selectively into these.
- The things we currently call "the Getting Started guides" (
- Tutorials are Marketing-owned (specifically Technical Content Marketing), with contribution from everyone welcome. The commented-out CODEOWNERS mapping of
content/tutorials/to@pulumi/docsdoesn't reflect this and should be corrected if CODEOWNERS is ever re-enabled. - A new hub at
/learnis in the works that pulls in all tutorials, templates, and examples — as well as blog posts categorized as tutorials. Like the Registry and pulumi.com/guides today, it will most likely be served by a separate web app rather than this repo.
Open items:
- Give
content/docs/iac/guides/a landing page. IaC holds the same guide content as the other product sections but has no_index.md, so the type is invisible in the IaC nav. Add an introduction page, titled "Guides," to match its siblings. - Reserve "tutorials" for the two things above. Don't introduce other "tutorial" sections inside
/docs/. Note that/learnis currently an alias of/tutorials, andcontent/learndoes not exist as a directory. - Bring team metadata current. The team-management repo may need tweaks (at least on the Marketing side) to reflect the ownership described here.
- CODEOWNERS is entirely commented out (
.github/CODEOWNERS), so no ownership is enforced — and the commented-out mapping doesn't fully match reality anyway (it assignscontent/tutorials/to@pulumi/docs, while actual ownership sits with Marketing). - Stale
content/learnreference: the docs-review criteria (.claude/commands/docs-review/references/docs.md) scope includescontent/learn, which doesn't exist. The/learnpath itself is slated to be taken over by the new learning-hub web app described above. - Untyped campaign directories: ~20 one-off landing directories under
content/(gads/,cjs26/,kubecon/,reinvent/, …) carry no declared type in repo metadata beyond falling into the "website" review domain. They are all Marketing-owned and treated here as product/campaign pages.