Writing style

While closely related to voice and tone, style is more about the mechanics of how writing (and content in general) is constructed. Where voice and tone are about emotion and personality, style is more about structure and technique.

The essentials

Always write like a human. Even when you’ve used an LLM to assist, your words belong to you.
Always respect the reader’s time and attention.
Give every piece a clear thesis or driving question.
Use headings to carry the structure and convey the gist.
Almost always, address the reader directly.
Nothing ships without revision and human review.

Respect the reader’s time and attention

Our time and attention are among our most precious resources. When writing for a human (which you should pretty much always be doing), always remember there’s someone on the other end of the line trying to get value out of your words as they read them. None of us has the time or energy to slog through vague, incomplete, unedited, or overly inflated prose.

See Drafting, revising, and reviewing below for guidance.

Natural voice

All of the copy we write should sound like a human being wrote it, even if an LLM helped to create it. Pulumians are people, and our readers assume the words we write are our own. So we write like the people we are, not like machines, avoiding patterns that signal generated text, such as:

Staccato sentence fragments used for emphasis. Like this. And this.
Leading negatives, with or without the usual em-dashes, like This isn’t just about foo — it’s about bar. Cut the negative, say it’s about bar, and get on with it.
Three-item series. They’re a big AI tell. They’re fine when you write them yourself, but LLMs use them as filler. Ensure they say what you mean and if not, revise or delete.
Overuse of tables. Unless the table is truly valuable as a table (i.e., it’s data), consider rewriting it as a list or in prose — or simply delete it.
Too many bullet lists. A few well-placed bullets are great, but a screenful of them is another AI signal. Consider revising as prose to break things up and make the writing more human.

As a rule: Never ship raw LLM output. Every piece of writing we produce must go through a human review and revision cycle in which you, as the author, bring the copy in line with how you — and how we — would say it. See Drafting, revising, and reviewing for details.

Person and point of view

Addressing the reader

In technical content for hands-on engagement (blogs, tutorials, how-to guides), we use the second-person singular perspective (you), not the first-person plural (we). This is because we aren’t doing anything — the reader is. So the focus is kept on their learning and experience: “In this walkthrough, you’ll build”, not “we’ll build”.

The same is true in most marketing content. Instead of “ESC enables teams and organizations to consolidate secrets management”, privilege “ESC lets you manage all of your secrets in one place”. There are exceptions, but as a rule, second person is clearer and more engaging — as well as how we’d most likely say it in conversation.

Attribution and accuracy

Every claim we make in our copy should come from an attributable source, even if that source is our own internal data.

Never round up, infer, or embellish.
If the source describes one person’s experience, don’t generalize it as “companies” or “teams”.
If the source doesn’t give a number, don’t invent or estimate one.

Grammar and punctuation

We use the Oxford (or serial) comma, so it’s “build, deploy, and manage”, not “build, deploy and manage”.
Human writers use em-dashes (”—”), so you can, too. Feel free to use em-dashes when you’re writing them yourself. Revise away, however, the em-dashes emitted by LLMs, because they’re strong markers of LLM-generated copy. Do not, however, simply swap them out for other punctuation like hyphens or commas, as that’s just another marker of lazily revised LLM-generated copy. Make the words and the phrasing both grammatically correct and your own.
Contractions are not only fine, they’re preferable, even in docs. (We write for people.)
Put commas and periods outside the closing quotation mark unless they belong to the quoted text to keep punctuation from looking like part of a literal. For example, write “us-west-2”, and a quoted phrase like “it just works”, with the punctuation outside.
Reserve “e.g.,” and “i.e.,” — both followed by commas — for parenthetical asides, and spell out “for example” or “that is” in running prose.

Dates, times, and numbers

Write dates as “June 14, 2026” in prose, and use ISO 8601 (“2026-06-14”) in technical and code contexts.
Write times in 12-hour form with a lowercase “am” or “pm”, and always include the time zone, as in “9:00am UTC”. Default to UTC unless there’s a good reason not to.
Use an en-dash for numeric ranges (“10–20”), commas in numbers of a thousand or more (“10,000”), and spelled-out scale for large round numbers (“$5 million”, not “$5,000,000”).

Code samples

When writing code samples:

Use four-space indentation for all languages except YAML and Go. With YAML, use two-space indentation. With Go, use tabs.
Use double-quotes across all languages, single quotes within double-quoted strings.
Use comments and highlights to call out important sections of the code. Keep comments brief, ideally to one line.
When quoting a section of code that’s indented in the source, omit the leading indentation. For example, to declare a local variable in the body of a JavaScript method belonging to a class (e.g., two levels of indentation), do this:
```
const foo = "bar";
```
Not this:
```
        const foo = "bar";
```
The latter may be truer to the source, but without local context, the leading space looks unintentional and can push longer lines and further nesting out of view.
Horizontal scrolling in code samples is usually fine, except when the code under discussion drifts out of view. Consider splitting up longer lines to ensure the important parts are visible at desktop width.

Split long CLI commands into multiple lines to help readers see what’s important:

pulumi do aws:s3:BucketV2 create \
    --aws:region us-west-2 \
    --aws:access-key <your-access-key-id> \
    --aws:allowed-account-ids <your-allowed-account-ids> \
    --force-destroy \
    --yes

Text formatting

Use code font (backticks) for code, commands, filenames, paths, environment variables, and literal values, as in pulumi up, ~/.pulumi, AWS_REGION, and true.
Use bold sparingly for the names of UI elements the reader acts on (“click Save”), and for the rare phrase that genuinely needs emphasis. Bold sprinkled throughout is both visually noisy and a common AI tell.
Use italics for a word or short term you’re introducing, defining, or describing — for example: setup is a noun, set up is a verb. Italics are also generally appropriate for emphasis, but should be used sparingly.
Write placeholders in angle brackets with code elements, like <your-access-key-id>, so it’s obvious what the reader should replace.

Headings and titles

Avoid clickbaity titles.
Always use sentence case for headings (e.g., “This is a heading”, not “This Is a Heading”).
Avoid ending headings with punctuation.
Use headings to communicate structure and content. Skimming only the headings, the reader should be able to discern the piece’s overall outline and what it’s about. Avoid clever headings that don’t convey meaning.
Nest headings properly. For example, don’t put an h3 (###) directly under an h1. Make it an h2 instead.
Keep SEO in mind. Use titles and headings that contain the keywords you’re targeting. This’ll make it easier for humans to find your content by helping the bots index and rank it.
Scrub for common LLMisms like “Stop doing X. Y.”, “Why this matters”, “What this unlocks”, and “What this means — and what it doesn’t”. See Generative AI for additional details.

Names and terminology

Always capitalize Pulumi product names correctly:
- Pulumi IaC
- Pulumi Cloud, Pulumi console, Pulumi Cloud console (but not Pulumi UI)
- Pulumi ESC (Environments, Secrets, and Configuration)
- Pulumi Neo
- Pulumi Deployments
- Pulumi Insights
- Pulumi Policies
- Pulumi IDP
Expand product names on first mention (“Pulumi ESC”), then use just the product name (“ESC”) afterward. Similarly, for non-Pulumi acronyms, spell out the acronym on first use, then use the abbreviation (e.g., “Virtual Private Cloud (VPC)”, then just “VPC”). Widely known acronyms (API, HTTP, REST) don’t need explanation.
Don’t overcapitalize. Only proper nouns should be capitalized — not concepts (even Pulumi-specific ones). So for example, it’s stack, not Stack; environment, not Environment; token, not Token; and infrastructure as code, not Infrastructure as Code.
The phrase infrastructure as code can be used as a noun or an adjective. The noun form (“infrastructure as code is the practice of…”) should never be hyphenated. The adjectival form (“Pulumi is an infrastructure-as-code tool”) may be hyphenated, but typically doesn’t need to be. If the sentence is clear and unambiguous without the hyphens, omit them.
Use public preview for pre-GA features, not public beta.
It’s open source when used as a noun (“Pulumi is open source”), but open-source when used as an adjective (“an open-source platform”); set up as a verb but setup as a noun; log in as a verb but login as a noun; and command line as a noun but command-line as an adjective.
Cloud and internet are both lowercase, and data center is two words. Frontend and backend are both one.
Match each project’s own casing for names like Kubernetes, GitHub, and npm. When a lowercase name like npm would land at the start of a sentence, reword so it doesn’t.

For which words to prefer or avoid for voice and tone, see words and phrases.

Images and alt text

Give every meaningful image alt text that describes its content or function in a few words. Omit phrases like “image of” and “screenshot of”, since screen readers already announce images.
Name image files descriptively, both for accessibility and for SEO. (See the review checklist.)

Lists

Introduce lists with a complete sentence, usually ending in a colon.
Write list items as complete sentences — capitalized, and ending with a period — unless the list is deliberately terse, like a set of single terms, in which case drop the periods. Either way, stay consistent within a single list.
Keep list items parallel. If the first one starts with a verb, they all should.
Only use lists when lists are called for, and prefer prose otherwise. See Natural voice for additional guidance.

Paragraphs

Keep paragraphs short, ideally to five sentences or fewer.
Separate paragraphs with a blank line.
Mind how paragraphs stack up on one another. Each one should follow from the last and set up the next. If two in a row feel interchangeable, or the jump between them is jarring, reorder or rewrite until the piece reads as one continuous line of thought.

Drafting, revision, and review

The following guide applies mainly to longer-form work like blog posts, docs, and whitepapers. Shorter pieces need less, but everything we publish still needs a human review before it gets published.

Drafting

Start by asking What do I want to say? Who is this for? and What will they want to know? Answering these questions up front helps you define your thesis and point of view, which makes the writing more interesting, and keeps things focused on what’s actually useful to the reader.
Sketch an outline before you start writing, so the structure is deliberate rather than something you figure out as you go.
Keep the scope under control. Any piece over 2,500 words is almost surely too long. If you can’t say what you need to say within that range, consider breaking it up into multiple pieces.

Revision

First drafts aren’t final drafts, they’re starting points. Every first draft deserves at least one revision.
When you’re finished with the first draft, read it aloud. If it sounds like you, great. If it doesn’t, revise the parts that don’t until it does. Remember, we’re humans writing for humans.
After that, set it aside — at least for an hour, ideally overnight — then give it another read. Does it say what you want it to say? Does it deliver the value the user expects? If not, continue revising.
Before reviewing, check your title, headings, and overall narrative progression. Sections should build on one another, and you should end with next steps and a clear (and contextually appropriate) call to action, not a “conclusion”.

Review

Conduct a self-review with your agent of choice, asking it to critique the piece from the reader’s point of view. The brand MCP server does this against the guidelines in this guide. Add the MCP server, paste your draft, and ask your agent for a review:

You're the reader I wrote this for: [describe your audience]. Read the draft
below and tell me: What's the one thing I'm trying to say, and does it land?
What questions does it leave unanswered? Where is it too long, too vague, or
too generic? What did I overlook, and how could it be stronger? Use the Pulumi
brand guidelines in your assessment.

Ensure you’ve covered the SEO basics:
- Use the keywords you’re targeting in the URL slug, page title, H1, and H2s.
- Use a descriptive, social media-friendly meta description.
- Use descriptive link text, and be sure to include links to relevant internal and external resources.
- Use well-labeled images.
Request a human review. Every piece — docs, blogs, landing pages, social posts, even ad copy — must be reviewed by one of your fellow Pulumians before you can publish it. Longer-form works must be reviewed by a member of the Editorial Board.
Address the feedback. If a human raises an issue, you must address and resolve the issue before publishing.