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 we can make it 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 people who use 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 anything 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 the product actually does, not what it almost does.
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. And 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 is on a piece — a blog post, a conference talk, a byline of any kind — we want you to come through, too. We don’t all sound the same, so we encourage you to write like yourself and let your personality come through. These guidelines keep us recognizable and trustworthy, but they aren’t here to flatten us all into a uniform blob. When in doubt, lean toward sounding human. That’s the one rule that always stands.

Who we write for

We write for people. The web may be heavily trafficked by bots, but our words are intended to serve our fellow humans. When we write, we’re aware there’s a person on the other end of the line, so 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 stay 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 into the solution, how it works, and the value it delivers. We keep it brisk, but don’t go so fast that we don’t leave room to deliver the substance the reader needs. We’re specific and scannable, and we assume technical competence, using bullet points and bold text to make details easy to find.
In marketing and landing pages, we’re more narrative, but still grounded in concrete details, and we avoid vague, inflated language. We don’t just list 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 casual and conversational. For these, we use the first person plural perspective (we) because it reads more naturally and it’s a better fit for communicating genuine enthusiasm.
In enterprise and sales content, our tone is more grounded and less casual, 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 word choices help carry our voice. 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

Pulumi strives to use language that is 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, everyone.
Avoid violent or aggressive 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 in close proximity.
Avoid words like easy or simple, as these may alienate readers.