--- name: writing-skills description: Help a Cloudflare employee write in Cloudflare's voice by interviewing them first, then drafting. Use for launch announcements, blog posts, changelog entries, PR descriptions, customer emails, apologies, product recommendations, and messages to teammates, or when someone asks to be "grilled" before writing. metadata: author: zeke version: "0.1" --- # Writing skills You're helping someone at Cloudflare write something in Cloudflare's voice. Don't write anything yet. Interview the writer first. A good piece comes from what they know, not from what you can make up. ## 1. Find the context The writer's first message usually says what they're writing, like "Let's announce a launch." If it doesn't, ask. Also find out who the reader is and where it'll be published: blog, changelog, email, chat, GitHub, or something else. ## 2. Grill them Ask one question at a time. Wait for each answer before asking the next. Push back on vague answers. If they say "it's much faster," ask how much faster, compared to what. Cover at least: - What's the one thing you want the reader to believe or do? Can you say it in one sentence? - Who's reading, and what do they already know? - Why does it matter to them? What changes for them? - What are the real numbers, names, commands, dates, and links? - Is there bad news, a tradeoff, or a mistake to own? - What should the reader do when they finish? Ask more if the context needs it. Stop once you have enough to write something specific. Don't fill gaps with guesses. If something's missing, ask, or leave a clearly marked placeholder like `[TODO: latency number]`. ## 3. Offer to let them talk it out Once you have the points, offer this: the writer records themselves talking through the points out loud, conversationally, then pastes in the transcript. Your job is to clean it up without meaningfully changing the content. Keep their words, their order, and their jokes. Cut filler, fix grammar, and tighten. If they'd rather not, draft it from their interview answers instead. ## 4. Draft Follow [references/style-guide.md](references/style-guide.md) for words and sentences, and [references/storytelling.md](references/storytelling.md) for the shape of the whole piece. Match the length and format to where it's published. A chat message to a teammate isn't a blog post. ## 5. Check Before you hand over the draft, check it against the style guide. In particular: - It opens with the news or a scene, not a warm-up. - The main point shows up early. - Numbers instead of adjectives. No "revolutionize," "leverage," "utilize," or "we're excited." - Active voice, with clear ownership ("we broke," not "an issue occurred"). - Few exclamation points, and sentence case headings. - It ends with something the reader can do. Then tell the writer what you weren't sure about and which placeholders still need real information. # Cloudflare writing style guide Guidelines for writing content in Cloudflare's voice and tone. ## How we write - **Talk like a human.** Avoid corporate speak or startup speak. Talk like you’re an engineer talking to another engineer in a conversation. Our roots are in engineering and open source, and our style reflects that. - Every startup is trying to "revolutionize" something, or whatever. Let’s set ourselves apart by not talking like every other company. - "Cloudflare makes it easy to build and deploy web applications", not "Cloudflare is a solution for accelerating the delivery of turnkey AI-powered applications." - Some examples for specific words: - "improve" not "revolutionize" - "use" not "leverage" - "use" not "utilize" - "help" not "assist" - "let" not "enable" - "make sure" not "ensure" - "adds value" or "is valuable" not "is a value-add" - **Prefer software engineering words to machine learning words.** - "Run", not "inference" or "prediction" - "Provide relevant context", not "RAG" - "Function calls that work", not "Agentic" - "Prompt model to think/plan", not "CoT" - "Add examples", not "FewShot" - "Someone with good written communication skills.", not "PromptEng" - **Don’t assume specialist knowledge.** You’re usually talking to sophisticated software engineers, so you can assume they have knowledge of software engineering, but don’t assume specific knowledge of machine learning, cloud infrastructure, or other specialized topics. A trick to getting this right is to imagine you are a fresh brain without any specialist knowledge, then read the thing you wrote, and see if it contains all the context for you to understand what is going on. - **Be honest.** Don’t try to hide reality. If you’re doing something for a reason, tell users that. They’ll appreciate the honesty. - **Make it clear.** Do the hard work to help users understand complex technical concepts. - **Be funny!** We don’t take ourselves too seriously. ## Tell a story Most of this guide is about words and sentences. This part is about the shape of the whole piece. Our best writing reads like someone telling you what happened and why it matters, not like a list of features. For examples, see [storytelling patterns](storytelling.md). - **Start with the news or a scene, not a warm-up.** - "The whole thing cost about $1,100 in tokens", not "In this post, we'll explore how we approached..." - Describing the problem vividly works too: "The moment an agent needs to deploy something [...] it slams face-first into a wall built for humans." - **Explain why it matters before how it works.** Give the stakes first, then the mechanics. If readers need background to see why the news matters, give the background first. Content Independence Day spends its first half on 30 years of Google's deal with content creators before it says what Cloudflare is doing. Delay the news on purpose, never because you're still warming up. - **Have a point, and make it early.** Pick the one thing you want the reader to believe, say it in the first few paragraphs, and use the rest of the piece to prove it. If you can't say it in one sentence, you're not ready to write yet. - **Deliver bad news plainly.** Say what happened, give the numbers, and own it with "we". Leave the wrong turns in: "We initially wrongly suspected the symptoms we were seeing were caused by a hyper-scale DDoS attack." Don't hide behind euphemisms like "restructuring" or "service degradation". - **Make it concrete.** - Use numbers instead of adjectives: "57% smaller", not "dramatically smaller". - Explain abstract ideas with everyday analogies. Billing by wall-clock time is like a taxi driver who stops to refuel and leaves the meter running. - Show the real thing. Include the command to run or the prompt to type, then show what happens. - **Write to the people affected.** When a change hits a specific group, like users of an open source project we're acquiring, talk to them directly and early. "What this means for Vite" comes before the business strategy. - **Back up promises with your track record.** If we've made a promise before and kept it, say so. The VoidZero announcement points to the Astro acquisition as proof that "open source and vendor-neutral" isn't just talk. - **Let a person show up.** Posts can have a byline and an "I". Giving a moment a name, like "Content Independence Day" or "Region: Earth", gives readers something to remember and repeat. - **End with something to do.** Give readers a command to run, a link to try, or a real ask for feedback ("Tell us what you think... We read every response."). Don't end on a summary of what you just said. # How to describe what Cloudflare is - **For a technical audience:** Cloudflare runs a global network that sits between your users and your infrastructure. It protects your sites and applications from attacks, speeds them up, and gives you a platform (Workers, Pages, R2, D1, and more) to build and run your own applications on that same network. - **For a non-technical audience:** Cloudflare helps make websites and apps faster, safer, and more reliable. Millions of businesses, from small websites to some of the largest companies in the world, run their online presence through Cloudflare's network so their sites stay up and load quickly, even under attack or heavy traffic. ## Nitty language things - Talk to "you", the user. - Use "Sentence case", not "Title Case" - **Don’t use acronyms.** - For example: - "Machine learning" not "ML" - "Language model" not "LLM" - There are some exceptions where the acronym is used more often than the expansion and it’s not machine learning jargon. For example, "AI" or "API". - **Prefer real words to jargon.** - Use plain language like "turned off" or "shut down", not "sunset". - **Use a direct, active voice.** Always be clear who is doing what to whom. - "We will listen to your complaint", not "Your complaint will be listened to". - "I’m sorry we broke your app", not "Apologies for the inconvenience". - [Good apologies say what you’re sorry about, why it was bad, and why it won’t happen again.](https://www.npr.org/2023/01/25/1150972343/how-to-say-sorry-give-good-apology) - "Apologies for the inconvenience" is the sort of thing a robot would say in a mass email. It’s canned, doesn’t take responsibility, and minimizes the problem. - That said, sometimes it feels more appropriate to use the passive voice, as in "Starting today, the per-second price for all public models is cut in half." — Use discretion. - **Don’t overuse exclamation points!** If you use them too much, it sounds like you’re on [a pepped up infomercial](https://www.youtube.com/watch?v=vywqnuVXZkU)! And, they lose their impact when you actually want to exclaim! - On changelog entries and blog posts, don’t say "today" or "launching" or "we're excited". Usually it’s just "X does blah" or "you can now X" and things like that. - Use normal words, not formal words. - "Let's help you with that", not "May we provide assistance we that" - "This will let you", not "This will enable you" - Pick a better verb instead of using adverbs. - Prefer verbs to nouns. - "We help users", not "We provide help to users" - But, don’t turn a noun into a verb if there isn’t a good verb. "Deploy your machine learning model to production", not "Productionize your machine learning model" - **Do I need this adjective?** - For example, "thousands of models" rather than "thousands of incredible models". - **Use American English spelling and grammar, rather than British English.** For example, "color" instead of "colour". - Keep heading hierarchies as flat as possible. Ideally, just one. ## Nitty formatting things - **Spell out email addresses instead of just using `mailto:` links.** If they’re just `mailto:` links where the link text isn’t the email address then it’s hard to use them if you use Gmail, and it unexpectedly opens the email client you don’t use. - **Don’t overuse bold text to highlight parts of text**. If bold text is needed to create some structure in a block of text, then the structure of those words should probably be improved. Perhaps there should be fewer words, more paragraphs, or you could use things like bullet points. - **Use ISO 8601 date formatting**. Use 2024-10-24, not 10/24/2024 or whatever. Alternatively, if you want to make it more human, "October 24, 2024". - Use `code formatting` for: - Filenames (e.g. "the `.gitignore` file") - Commands when mentioned in a sentence (e.g. "The `npm create cloudflare@latest` command you ran in Step 1") - If the reader is supposed to run the command, put it in a code block, not inline code formatting. ## Inspiration - [GOV.UK style guide](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style#bold) - Fly.io - [https://fly.io/blog/free-postgres/](https://fly.io/blog/free-postgres/) - [https://news.ycombinator.com/item?id=30018551](https://news.ycombinator.com/item?id=30018551) - [https://fly.io/blog/we-raised-a-bunch-of-money/](https://fly.io/blog/we-raised-a-bunch-of-money/) - [https://zachholman.com/posts/how-github-writes-blog-posts/](https://zachholman.com/posts/how-github-writes-blog-posts/) - [https://web.archive.org/web/20120713145852/https://www.gov.uk/designprinciples/styleguide](https://web.archive.org/web/20120713145852/https://www.gov.uk/designprinciples/styleguide) - [https://docs.rackspace.com/docs/style-guide/](https://docs.rackspace.com/docs/style-guide/) - [https://monzo.com/tone-of-voice/](https://monzo.com/tone-of-voice/) - [https://handbook.sourcegraph.com/company-info-and-process/communication/content_guidelines/](https://handbook.sourcegraph.com/company-info-and-process/communication/content_guidelines/) ## Style guide for LLMs Here’s a stripped down version of this style guide that can fit compactly into the context window of an LLM: ``` Cloudflare style guide - Talk like a human, not a corporation. - Avoid corporate and startup jargon. - Be clear, direct, and conversational. - Don’t oversell or exaggerate; be specific. - Use humor, but make sure it’s inclusive and accessible. - Use simple, common words (e.g., "improve" not "revolutionize," "use" not "leverage"). - Avoid acronyms unless commonly understood (e.g., AI, API). - Prefer real words over jargon (e.g., "turn off" not "sunset," "run" not "inference"). - Use active voice (e.g., "We will listen to your complaint," not "Your complaint will be listened to"). - Don’t assume specialist knowledge. - Use gender-neutral and inclusive language. - Avoid ableist and exclusionary terms ("crazy," "lame," etc.). - Avoid words like "easy," "simply," or "just do X." - Use sentence case, not Title Case. - Use bold only for UI elements, not emphasis. - Use inline code formatting for filenames and commands. - End full sentences with periods. - Spell out large numbers (e.g., "7 billion parameters"). - Use ISO 8601 dates (YYYY-MM-DD) or human-readable formats (e.g., "October 24, 2024"). - Use American English spelling and grammar (e.g., "color" not "colour"). - Avoid unnecessary mentions of "API" or "platform" unless needed for clarity. - Be honest. Don’t hide reality. - Talk directly to "you," the user. - Minimize exclamation points. - Open with the news or a scene, not a preamble. - Explain why it matters before how it works. - Make one clear point early, then back it up. - Deliver bad news plainly: what happened, the numbers, and "we" owning it. - Explain abstract ideas with concrete numbers, analogies, and real commands. - End with something the reader can do. ``` # Storytelling patterns These patterns come from Cloudflare blog posts by people known for having the Cloudflare voice. They show how good posts are built: how they open, how they handle bad news, how they make abstract ideas concrete. Word choice and grammar are covered in the style guide. This file is about storytelling. One caveat: most of these posts have more than one author. Read them as examples of Cloudflare voice in general, not as a fingerprint of any one person. The Cap'n Web post, for example, is mostly Kenton Varda talking, even though Steve Faulkner is also on the byline. ## Openings The best posts start with the news or a scene. "We've been working on something new." "The whole thing cost about $1,100 in tokens." "It slams face-first into a wall built for humans." Nobody opens with "In this post, we'll explore..." Some delay the news on purpose. [Content Independence Day](https://blog.cloudflare.com/content-independence-day-no-ai-crawl-without-compensation/) spends most of its first half on the history of Google's deal with content creators, starting with Larry Page and Sergey Brin's Backrub project, before it says what Cloudflare did. By the time you reach the announcement, you already know why it matters. Others make their argument in the first few paragraphs and spend the rest proving it. The [Iran post](https://blog.cloudflare.com/two-months-later-internet-use-in-iran-during-the-mahsa-amini-protests/) and the [Free plan post](https://blog.cloudflare.com/cloudflares-commitment-to-free/) both work this way. ## Bad news Matthew Prince's [outage postmortem](https://blog.cloudflare.com/18-november-2025-outage/) admits Cloudflare "wrongly suspected" a DDoS attack before it explains the real cause. The wrong turn stays in the story. The [layoff post](https://blog.cloudflare.com/building-for-the-future/) gets to the number in its second sentence: more than 1,100 people. No "restructuring," no "right-sizing." "We" does real work in these posts. "We are sorry for the impact to our customers" lands differently than "We apologize for any inconvenience," because someone is actually taking responsibility. The technical detail stays in, too. The [Thanksgiving 2023 incident post](https://blog.cloudflare.com/thanksgiving-2023-security-incident/) ends with a table of IP addresses, file hashes, and domains so other companies can check their own logs. ## Making it concrete Numbers do the work adjectives usually try to do: "$1,100 in tokens," "57% smaller," "1,100 employees." Sometimes they're stacked for effect. Content Independence Day says it's gotten about 10 times harder to get traffic from Google, 750 times harder from OpenAI, and 30,000 times harder from Anthropic. One number is a fact. Three is an argument. Analogies handle the abstract stuff. The [Workers pricing post](https://blog.cloudflare.com/workers-pricing-scale-to-zero/) explains billing by duration with a taxi driver who stops for gas and leaves the meter running. Prince describes an AI model as a block of swiss cheese, where new content is valuable if it fills one of the holes. The developer posts show their work. The [temporary accounts post](https://blog.cloudflare.com/temporary-accounts/) gives you the exact prompt to paste into your coding agent, then walks through what the agent does next. ## Trust over time The [VoidZero acquisition post](https://blog.cloudflare.com/voidzero-joins-cloudflare/) promises Vite will stay open source and vendor-neutral, then backs that up by pointing at Astro: "We made the same kind of commitment when Astro joined Cloudflare earlier this year. Astro is still open source, and still deploys anywhere." The blog's own history becomes the evidence. Acquisition posts also talk to the affected community first. "What this means for Vite" is written for Vite users, and the business rationale comes later. ## Personality Individual voices come through, even on co-bylined posts. Kenton writes "a protocol I (Kenton) created a decade ago," and nobody edited it out. Names stick. "Content Independence Day" and "[Region: Earth](https://blog.cloudflare.com/best-place-region-earth-inference/)" give readers something to remember and repeat. And sometimes a post jokes about itself. The Region: Earth post ends with a deliberately cheesy AI-generated paragraph ("So buckle up, folks..."), followed by: "This wrap up message may have been generated by AI, but the sentiment is genuine." ## What's missing Almost every post here is a launch, an acquisition, or an incident. The Iran post is the only exception. If you find good Cloudflare writing that isn't tied to an announcement, add it. ## Posts - [Agents can now create Cloudflare accounts, buy domains, and deploy](https://blog.cloudflare.com/agents-stripe-projects/), by Sid Chatterjee and Brendan Irvine-Broque - [Our container platform is in production. It has GPUs. Here's an early look](https://blog.cloudflare.com/container-platform-preview/), by Brendan Irvine-Broque - [Temporary Cloudflare Accounts for AI agents](https://blog.cloudflare.com/temporary-accounts/), by Sid Chatterjee, Celso Martinho, and Brendan Irvine-Broque - [Introducing: Cloudflare Agents](https://blog.cloudflare.com/agents-on-cloudflare/), by Nevi Shah, Matt Simpson, and Fred Schott - [Astro is joining Cloudflare](https://blog.cloudflare.com/astro-joins-cloudflare/), by Fred Schott - [The best place on Region: Earth for inference](https://blog.cloudflare.com/best-place-region-earth-inference/), by Rita Kozlov, James Allworth, and Seph Zdarko - [Reaffirming our commitment to free](https://blog.cloudflare.com/cloudflares-commitment-to-free/), by Nitin Rao, Liam Reese, and James Allworth - [Two months later: Internet use in Iran during the Mahsa Amini Protests](https://blog.cloudflare.com/two-months-later-internet-use-in-iran-during-the-mahsa-amini-protests/), by James Allworth - [Building for the future](https://blog.cloudflare.com/building-for-the-future/), by Matthew Prince and Michelle Zatlyn - [Content Independence Day: no AI crawl without compensation!](https://blog.cloudflare.com/content-independence-day-no-ai-crawl-without-compensation/), by Matthew Prince - [Cloudflare outage on November 18, 2025](https://blog.cloudflare.com/18-november-2025-outage/), by Matthew Prince - [Thanksgiving 2023 security incident](https://blog.cloudflare.com/thanksgiving-2023-security-incident/), by Matthew Prince, John Graham-Cumming, and Grant Bourzikas - [Piecing together the Agent puzzle: MCP, authentication & authorization, and Durable Objects free tier](https://blog.cloudflare.com/building-ai-agents-with-mcp-authn-authz-and-durable-objects/), by Rita Kozlov, Dina Kozlov, and Vy Ton - [Replicate is joining Cloudflare](https://blog.cloudflare.com/replicate-joins-cloudflare/), by Rita Kozlov - [New Workers pricing: never pay to wait on I/O again](https://blog.cloudflare.com/workers-pricing-scale-to-zero/), by Rita Kozlov and Brendan Irvine-Broque - [Cap'n Web: a new RPC system for browsers and web servers](https://blog.cloudflare.com/capnweb-javascript-rpc-library/), by Kenton Varda and Steve Faulkner - [How we rebuilt Next.js with AI in one week](https://blog.cloudflare.com/vinext/), by Steve Faulkner - [VoidZero is joining Cloudflare](https://blog.cloudflare.com/voidzero-joins-cloudflare/), by Evan You and Steve Faulkner