Voice & tone

Everything we put out into the world — every blog post, doc, page, guide, deck, and social-media post — is an expression of the Pulumi brand. The content we create doesn't exist separately from the brand; it is the brand, and one of the main ways our users connect with us.

Voice

Our voice — the language we use and how we use it — should be as authentic and consistent as possible across all of our communications, from blogs and demos to case studies and whitepapers. How we communicate is an expression of who we are, so we do our best to adhere to certain key principles.

Practitioner-first. Most of our content is written for users of technical products like ours, so we write like engineers in conversation with engineers, with the words and language our audience uses, without dumbing things down or dressing things up.
Direct and confident. Technical people appreciate clarity, so we say what we mean, and we're tactfully and respectfully open about our opinions when we have them. When we're talking about Pulumi, we're clear about what our products actually do and don't do.
Concrete over abstract. Wherever possible, we show, don't tell, with examples and concrete numbers where it helps. "A P99 performance improvement of 93%" is better than "significantly faster", and "supports AWS and Azure" is better than "supports most major cloud providers". Ambiguity leads to confusion.
Honest and respectful. We openly acknowledge real-world tradeoffs and alternatives because that's what our audience needs and appreciates. "Already happy with Pulumi open source? Many teams are — and we love that." That's true, so we say it. We never trash competitor brands or products, and when Pulumi isn't the right fit, we say that too, because doing so builds trust, and trust is what it's all about.
Warm, but not cute. We're genuinely approachable and conversational, so our prose should reflect that ("it just works", "Pulumi takes care of the rest"), but we don't force humor or cleverness. We keep it light, but always professional.

Everywhere we communicate, we should sound like ourselves: human, kind, warm, approachable, empathetic, opinionated but balanced, and honest. Authenticity and trust, above all, are the goal.

Your own voice

Our collective voice is important, but when your name's on a piece, like a blog or a conference talk, we want your voice and personality to come through as well. The purpose of this guide is to help us keep our communications consistent, not to flatten us all into a uniform blob. When in doubt, just write like the human you are. See Drafting, revision, and review for help.

Who we write for

We write for our fellow humans. While the web may be trafficked increasingly by bots, our words are ultimately meant for people. As we write, we're aware there's a person on the other end of the line, and we craft our words accordingly, even if what we're writing is intended to connect with that person by way of a bot.

Tone by context

While our voice should be consistent, the tone we use may shift depending on audience and context.

In product and technical content, we lead with the motivating problem, then move to the solution, how it works, and the value it delivers. We keep it brisk, but don't go so fast that we skip over the substance the reader needs. We're specific and scannable, and we assume technical competence, using headings and bullet points to make details easy to find.
In marketing and landing pages, we're more narrative, but still grounded in concrete details, and we avoid the vague, inflated language of typical marketing content. Rather than just listing features, we communicate the value those features deliver, because that's what the reader cares about. Context and well-chosen examples are much better than feature lists, which require the reader to fill in the blanks on their own.
In community and social content, we're genuine, casual, and conversational. For these, we generally use the first-person plural perspective (we), because it reads more naturally and is closer to how we'd communicate with the reader in person.
In enterprise and sales content, our tone is less casual, more grounded and formal, but still human, and we're careful to avoid using overly promotional, salesy, or marketing-heavy language.

For guidance on whether to address the reader as you or we, see Person and point of view.

Words and phrases

The following sections are included to help us keep our language consistent. For how to spell, capitalize, and hyphenate specific terms, including Pulumi product names, see Names and terminology.

Prefer

Engineers and developers over users or customers. (The latter are colder and less personal.)
Humans and agents as a natural pairing when describing who Pulumi is built for.
Agents or coding agents when referring to AI agents that provision and manage infrastructure.
Building blocks, components, and composable when describing our compositional capabilities.
Estate for the full scope of an organization's infrastructure, as opposed to the less specific environment or footprint.
Build, deploy, ship, and manage as active, concrete verbs.
Works with or integrates with over the more awkward and inflated leverages or utilizes.
Short sentences and parallel structure in lists.

Avoid

Superlatives without evidence like the best, the only, the most powerful, etc.
Tired buzzwords like synergy and the like.
Exclamation points and emojis just about everywhere other than social-media posts.
Sharply negative or combative language and profanity.

Inclusive language

We strive to use language that's clear, inclusive, and respectful.

Avoid ableist terms. Instead of crazy, use wild. Instead of dummy, use placeholder.
Avoid unnecessarily gendered language. Instead, use words like folks and everyone.
Avoid violent or aggressive imagery and terms like kill or clobber.
Avoid pop-culture references that may not be globally understood.
When writing docs, consider select or choose over click.
Instead of go to, use navigate to.
Avoid directional terms like above or below unless the reference is close at hand.
Avoid words like easy or simple, as these may alienate readers.