|
| 1 | +# TAXONOMY.md — Content types for pulumi.com |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Why this document exists |
| 6 | + |
| 7 | +The word **"guides"** currently refers to five different things: |
| 8 | + |
| 9 | +1. 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 carry `title: Guides`; `content/docs/iac/guides/` holds the same kind of content but has no landing page of its own). |
| 10 | +2. 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. |
| 11 | +3. Marketing also publishes **pulumi.com/tutorials**, which are occasionally referred to as guides. |
| 12 | +4. The Registry currently republishes Pulumi examples and labels them "how-to guides". |
| 13 | +5. Historic docs URLs like `/docs/guides/...` still circulate and are handled by redirects (`scripts/redirects/`). |
| 14 | + |
| 15 | +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: |
| 16 | + |
| 17 | +- `AGENTS.md` — file placement and agent workflow rules |
| 18 | +- `STYLE-GUIDE.md` — prose and formatting rules |
| 19 | +- `BLOGGING.md` — blog-specific authoring rules |
| 20 | +- `CONTRIBUTING.md` — review pipeline and domain labels |
| 21 | + |
| 22 | +## Ownership vocabulary |
| 23 | + |
| 24 | +Teams: |
| 25 | + |
| 26 | +- **Docs** — the documentation team (`@pulumi/docs` in the intended CODEOWNERS mapping). |
| 27 | +- **Community Eng** — developer relations and advocacy. |
| 28 | +- **Marketing** — technical content marketing, product marketing, and growth. |
| 29 | +- **Eng/Product** — product engineering and product management. |
| 30 | + |
| 31 | +"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. |
| 32 | + |
| 33 | +## The taxonomy |
| 34 | + |
| 35 | +### Conceptual documentation ("Concepts") |
| 36 | + |
| 37 | +**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. |
| 38 | + |
| 39 | +- **Lives at:** `content/docs/*/concepts/` (e.g. `content/docs/iac/concepts/`, `content/docs/esc/concepts/`) |
| 40 | +- **Examples:** [Stacks](https://www.pulumi.com/docs/iac/concepts/stacks/), [State and backends](https://www.pulumi.com/docs/iac/concepts/state-and-backends/) |
| 41 | +- **Owns:** Docs |
| 42 | +- **Contributes:** Eng/Product (feature knowledge), Community Eng |
| 43 | +- **Consumes:** Practitioners building an understanding of how Pulumi works |
| 44 | + |
| 45 | +### Guides |
| 46 | + |
| 47 | +**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](https://diataxis.fr/) sense, a guide here can take the form of either a "how-to guide" or an "explanation" — both fit the needs of these sections. |
| 48 | + |
| 49 | +- **Lives at:** `content/docs/iac/guides/`, `content/docs/esc/guides/`, `content/docs/deployments/guides/`, `content/docs/idp/guides/` |
| 50 | +- **Examples:** [Migrating from Terraform](https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/from-terraform/), ESC + GitHub Actions integration guides |
| 51 | +- **Owns:** Docs |
| 52 | +- **Contributes:** Eng/Product, Community Eng, community |
| 53 | +- **Consumes:** Practitioners new to Pulumi or seeking help with (or a better understanding of) a particular product or feature |
| 54 | + |
| 55 | +### Tutorials |
| 56 | + |
| 57 | +**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. |
| 58 | + |
| 59 | +- **Lives at:** `content/tutorials/` → [pulumi.com/tutorials](https://www.pulumi.com/tutorials/) (also aliased at `/learn`) and `content/docs/*/get-started` |
| 60 | +- **Examples:** IaC Get Started, Deployments Get Started, ESC Get Started, Pulumi Fundamentals (3-part module), "Importing AWS Infrastructure" |
| 61 | +- **Owns:** Marketing |
| 62 | +- **Contributes:** Docs, Eng/Product |
| 63 | +- **Consumes:** Newcomers and learners |
| 64 | + |
| 65 | +**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. |
| 66 | + |
| 67 | +### Reference |
| 68 | + |
| 69 | +**Definition:** Lookup material — exhaustive, structured, factual. Optimized for finding one precise answer, not for reading front to back. |
| 70 | + |
| 71 | +- **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](https://www.pulumi.com/registry/) (published from its own pipeline) |
| 72 | +- **Examples:** `pulumi up` CLI reference, Pulumi Python SDK API Reference |
| 73 | +- **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) |
| 74 | +- **Contributes:** Eng/Product |
| 75 | +- **Consumes:** Practitioners who know what they're looking for |
| 76 | + |
| 77 | +### Marketing guides (pulumi.com/guides) |
| 78 | + |
| 79 | +**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." |
| 80 | + |
| 81 | +- **Lives at:** [pulumi.com/guides](https://www.pulumi.com/guides/) — **not in this repository**; published from a separate marketing pipeline |
| 82 | +- **Owns:** Marketing |
| 83 | +- **Contributes:** Community Eng, Eng/Product (technical validation) |
| 84 | +- **Consumes:** Evaluators and buyers scoping a solution |
| 85 | + |
| 86 | +> **Status: effectively end-of-life.** This content is being folded selectively into [Tutorials](#tutorials). Going forward, "Guides" refers only to the docs guides above — see [Naming decisions](#naming-decisions-and-open-items). |
| 87 | +
|
| 88 | +### Topics |
| 89 | + |
| 90 | +**Definition:** Educational pages or topic clusters answering a definitional search query ("What is GitOps?"). Product-light, concept-heavy. |
| 91 | + |
| 92 | +- **Lives at:** `content/what-is/` (section title: "Cloud Engineering Concepts Explained") |
| 93 | +- **Owns:** Marketing |
| 94 | +- **Contributes:** Docs, Community Eng |
| 95 | +- **Consumes:** Evaluators early in research |
| 96 | + |
| 97 | +### Blog posts |
| 98 | + |
| 99 | +**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:`). |
| 100 | + |
| 101 | +- **Lives at:** `content/blog/` |
| 102 | +- **Owns:** Marketing. Individual blog authors own the accuracy of their content at time of publishing. Marketing owns the rest, including design, editorial, and amplification. |
| 103 | +- **Contributes:** Everyone — Eng/Product, Community Eng, Docs, Marketing, guest authors |
| 104 | +- **Consumes:** Community, customers, news readers |
| 105 | + |
| 106 | +### Case studies |
| 107 | + |
| 108 | +**Definition:** Customer success narratives — who they are, what problem they had, how Pulumi solved it, with quotes and metrics. |
| 109 | + |
| 110 | +- **Lives at:** `content/case-studies/` |
| 111 | +- **Owns:** Marketing |
| 112 | +- **Contributes:** Sales/CS (customer relationships), Community Eng |
| 113 | +- **Consumes:** Buyers seeking social proof |
| 114 | + |
| 115 | +### Product and campaign pages |
| 116 | + |
| 117 | +**Definition:** Template-driven pages that sell — product pages, solution pages, pricing, comparison/topic landing pages, and ad-campaign landing pages. |
| 118 | + |
| 119 | +- **Lives at:** `content/product/`, `content/solutions/`, `content/topics/`, `content/pricing/`, `content/why-pulumi/`, `content/gads/`, and ~20 similar campaign directories |
| 120 | +- **Owns:** Marketing |
| 121 | +- **Contributes:** Eng/Product (feature accuracy), Docs (technical review) |
| 122 | +- **Consumes:** Evaluators and buyers |
| 123 | + |
| 124 | +### Events and workshops |
| 125 | + |
| 126 | +**Definition:** Registration and recap pages for webinars, workshops, and conference presence. |
| 127 | + |
| 128 | +- **Lives at:** `content/events/` |
| 129 | +- **Owns:** Marketing and Community Eng, jointly (Marketing owns promotion and pages; Community Eng owns technical content delivered) |
| 130 | +- **Consumes:** Community members and prospects |
| 131 | + |
| 132 | +### Releases and Changelog |
| 133 | + |
| 134 | +**Definition:** Dated records of what shipped — one changelog entry per change, plus launch pages. |
| 135 | + |
| 136 | +- **Lives at:** `content/releases/`, `content/releases/changelog/` |
| 137 | +- **Owns:** Marketing |
| 138 | +- **Contributes:** Eng/Product, Docs, Community Eng |
| 139 | +- **Consumes:** Existing and prospective users tracking product evolution |
| 140 | + |
| 141 | +### Templates |
| 142 | + |
| 143 | +**Definition:** Starter kits for generating new Pulumi projects with `pulumi new`. |
| 144 | + |
| 145 | +- **Lives at:** `content/templates/` (sourced from https://github.com/pulumi/templates); includes both starter and architecture templates. |
| 146 | +- **Owns:** Marketing |
| 147 | +- **Contributes:** Eng/Product, Community Eng |
| 148 | +- **Consumes:** Practitioners bootstrapping new projects |
| 149 | + |
| 150 | +### Example programs |
| 151 | + |
| 152 | +**Definition:** Testable programs designed for embedding into docs and tutorials. |
| 153 | + |
| 154 | +- **Lives at:** `static/programs/`, tested via `scripts/programs/test.sh` |
| 155 | +- **Owns:** Docs |
| 156 | +- **Contributes:** Eng/Product, Marketing, Community Eng |
| 157 | +- **Consumes:** Practitioners engaging with the docs. Every docs page that embeds an example should ideally use one of these programs. |
| 158 | + |
| 159 | +## Summary table |
| 160 | + |
| 161 | +| Type | One-line definition | Lives at | Owns | Contributes | Consumes | |
| 162 | +|---|---|---|---|---|---| |
| 163 | +| Conceptual docs | Explains how Pulumi works and why | `content/docs/*/concepts/` | Docs | Eng/Product, Community Eng | Practitioners | |
| 164 | +| Guides | Walkthroughs designed for understanding and using Pulumi | `content/docs/*/guides/` | Docs | Eng/Product, Community Eng, community | Practitioners | |
| 165 | +| Tutorials | Sequenced hands-on learning | `content/tutorials/` | Marketing | Docs, Eng/Product | Newcomers, learners | |
| 166 | +| Reference | Exhaustive lookup material | `content/docs/reference/`, generated CLI docs | Docs + Eng/Product | Eng/Product | Practitioners | |
| 167 | +| Topics | Adjacent, industry-relevant educational content ("what is X") | `content/what-is/` | Marketing | Docs, Community Eng | Learners, evaluators | |
| 168 | +| Blog posts | Point-in-time posts; historical | `content/blog/` | Marketing | Everyone | Community | |
| 169 | +| Case studies | Customer success stories | `content/case-studies/` | Marketing | Sales/CS, Community Eng | Buyers | |
| 170 | +| Product/campaign pages | Pages that sell | `content/product/`, `solutions/`, `gads/`, … | Marketing | Eng/Product, Docs | Evaluators, buyers | |
| 171 | +| Events & workshops | Registration/recap pages | `content/events/` | Marketing + Community Eng | — | Community, prospects | |
| 172 | +| Releases & changelog | Dated record of what shipped | `content/releases/` | Marketing | Eng/Product, Docs | Existing and prospective users | |
| 173 | +| Templates | Runnable starting points | `content/templates/` | Marketing | Eng/Product, Community Eng | Practitioners | |
| 174 | +| Example programs | Tested, embeddable code | `static/programs/` | Docs | Eng/Product, Community Eng | Practitioners | |
| 175 | + |
| 176 | +## Naming decisions and open items |
| 177 | + |
| 178 | +The "guides" collision described at the top of this document has been resolved as follows (agreed in [PR #20803](https://github.com/pulumi/docs/pull/20803)): |
| 179 | + |
| 180 | +1. **"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](https://diataxis.fr/) 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. |
| 181 | +1. **"Tutorials" refers to either:** |
| 182 | + - 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. |
| 183 | + - The things that live at [pulumi.com/tutorials](https://www.pulumi.com/tutorials/). The content at pulumi.com/guides is being folded selectively into these. |
| 184 | +1. **Tutorials are Marketing-owned** (specifically Technical Content Marketing), with contribution from everyone welcome. The commented-out CODEOWNERS mapping of `content/tutorials/` to `@pulumi/docs` doesn't reflect this and should be corrected if CODEOWNERS is ever re-enabled. |
| 185 | +1. **A new hub at `/learn` is in the works** that pulls in all tutorials, templates, and examples — as well as blog posts categorized [as tutorials](https://www.pulumi.com/blog/category/tutorials/). Like the Registry and pulumi.com/guides today, it will most likely be served by a separate web app rather than this repo. |
| 186 | + |
| 187 | +Open items: |
| 188 | + |
| 189 | +1. **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. |
| 190 | +1. **Reserve "tutorials" for the two things above.** Don't introduce other "tutorial" sections inside `/docs/`. Note that `/learn` is currently an alias of `/tutorials`, and `content/learn` does not exist as a directory. |
| 191 | +1. **Bring team metadata current.** The team-management repo may need tweaks (at least on the Marketing side) to reflect the ownership described here. |
| 192 | + |
| 193 | +## Known gaps |
| 194 | + |
| 195 | +- **CODEOWNERS is entirely commented out** (`.github/CODEOWNERS`), so no ownership is enforced — and the commented-out mapping doesn't fully match reality anyway (it assigns `content/tutorials/` to `@pulumi/docs`, while actual ownership sits with Marketing). |
| 196 | +- **Stale `content/learn` reference:** the docs-review criteria (`.claude/commands/docs-review/references/docs.md`) scope includes `content/learn`, which doesn't exist. The `/learn` path itself is slated to be taken over by the new learning-hub web app described above. |
| 197 | +- **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. |
0 commit comments