Skip to main content

​
Docs writing and positioning guide

Severity: blocking. Every rule in this file is mandatory. Flag violations as bugs, not suggestions. Do not approve a PR that violates any of these rules.

​
Positioning

Browserbase docs are a demand-capture surface. They may use a customer’s problem language when needed for discovery or clarity, but they must always resolve that problem using Browserbase’s approved product language.
  • Ladder to the roof. Every page must support the core narrative: “The web wasn’t built for agents. Browserbase is.” Position Browserbase in browser agents, not the entire agents category.
  • Lead with one pillar. For developers, lead with browsers that work where APIs cannot. For leadership, lead with one platform instead of five vendors. At most one other pillar may support the lead.
  • Keep browsers at the center. Do not position Browserbase as generic computer-use software or commodity infrastructure. Do not use roads, pipes, raw compute, or similar metaphors that reduce Browserbase to price per session.
  • Use only approved proof. Do not invent statistics, customer names, performance claims, or superlatives. The approved proof points are 35m+ browser sessions per month; 10,000 customers; Ramp, Microsoft, and Lovable; SOC-2 Type II; Stagehand up to 2x faster with approximately 30% lower cost on repeated actions; and Functions with under 5ms latency to the browser.
  • Use the 15/85 or 25/75 API statistic only as an illustrative hook. Never use it as a headline or as a claim Browserbase must defend. For leadership audiences, prefer the trend framing that 80% of an agent’s context lives on the web.
  • Never name competitors in public copy. This includes comparison copy unless PMM has explicitly reviewed it. Do not name Firecrawl, Browser Use, Kernel, HyperBrowser, Steel, Browserless, Anchor, Parallel, Exa, or Tavily.
  • Do not oversell agent intelligence. Browserbase promises browsers, identity, observability, and infrastructure, not smarter agents.

​
Writing style

These rules are non-negotiable. Flag every violation, even minor ones.
  • Brevity is mandatory. Every sentence must earn its place. Cut filler words (“just,” “simply,” “basically,” “actually,” “in order to,” “it should be noted that”). If a sentence can be shorter without losing meaning, it must be.
  • Sentence case for all titles and headings. Only capitalize the first word and proper nouns (e.g., “How Browserbase took over the world” not “How Browserbase Took Over the World”). Flag any title-cased heading as a bug.
  • Conversational tone, not casual. Text should sound natural if spoken aloud. Contractions are encouraged (“you’ll,” “it’s,” “don’t”). No slang, no filler phrases like “let’s dive in” or “as you can see.”
  • Sound like an engineer stating a fact. Lead with the outcome, prefer explicit language over clever phrasing, and avoid keynote language such as “revolutionizing how AI interacts with the digital world.”
  • Active voice only. Flag any use of passive voice (e.g., “the session is created” should be “Browserbase creates the session” or “you create the session”).
  • Second person (“you”) for the reader. Always address the reader as “you,” never as “we.” Flag any use of “we” to mean the reader.
  • Oxford comma required. Always use a comma before “and” or “or” in a list of three or more items. Flag missing oxford commas.
  • Capitalize product names (Browserbase, Stagehand, Playwright, Functions, Search, Identity, etc.) but default to lowercase for everything else. Flag inconsistent capitalization.
  • No em dashes. Flag every U+2014 em dash character in docs copy, frontmatter, tables, and code comments as blocking. Use judgment to recommend the clearest rewrite with a period, colon, comma, parentheses, or a rephrased sentence. Plain hyphens are allowed when they are semantically correct, such as compounds, ranges, product names, and command flags. Do not recommend replacing an em dash with a hyphen that still acts like an em dash.
    • Exception: em dashes are allowed inside fenced example content that readers copy verbatim: system prompts, model prompts, sample task strings, and pasted config/log snippets. The Agent copies these into its own runtime, so preserve authorial voice.
  • Agent casing. Capitalize Agent and Agents when the word refers to the Browserbase product/feature or a concrete instance of it. Lowercase only when discussing agents as a generic industry concept. Flag mismatches.
    • Write “Create an Agent,” “your first Agent run,” “the Agent’s goal,” “Job Finder Agent,” “an Agent renders each page.”
    • Write “browser agents adapt to sites that change” or “the SDK for browser agents” (generic category).
    • API endpoint names track the OpenAPI spec: “Run an Agent,” “Create an Agent,” “List Agents.”
  • No secrets in example prompts. Never embed credentials, API keys, tokens, or personal data directly in example prompts, task strings, or code samples. Use %variableName% placeholders (Agent variables) or environment variables ($BROWSERBASE_API_KEY). Flag inline credentials as blocking.
  • No placeholder or dead links. Flag any ](#) or obviously broken href as blocking. Use canonical paths for repeated destinations:
    • Stagehand: /welcome/quickstarts/stagehand
    • Dashboard: https://www.browserbase.com/overview
    • Agents overview: /platform/agents/overview
    • Agents API endpoints under /reference/api/....
  • Never use “we,” “us,” or “our” for Browserbase. Always refer to the company by name. This applies to first-person plural in any form: subject (“we”), object (“us”), possessive (“our”), and contractions (“we’re,” “we’ve,” “we’ll”). Flag every instance.
    • Write “Browserbase recommends” not “we recommend.”
    • Write “Browserbase provides” not “we provide.”
    • Write “Browserbase’s infrastructure” not “our infrastructure.”
    • Write “Browserbase supports both transports” not “we support both transports.”
    • Exception: direct quotes from customers or team members in case studies.

​
Tagline

  • Current: “Give your agents access to the whole web.”
  • Deprecated (flag if seen): “Agents can now browse and interact with the web like humans.”
  • Deprecated (flag if seen): “Autonomously read, write, and perform tasks on the web with a headless browser.”

​
Structure and formatting

  • Make content easy to skim: use bullet points, break up text, include images/videos/tables where helpful.
  • Headlines should outline a clear structure and make sense on their own.
  • Lead with the main information. Get to the point fast, add details later. Front-load keywords for scanning.
  • Make customer choices and next steps obvious.

​
Code examples

  • Default to SDK code examples over raw API calls whenever possible.
  • Label every Node.js code block as Node.js, including snippets written in TypeScript or JavaScript. Keep the syntax language for highlighting, then add the visible label, such as typescript Node.js or javascript Node.js. Never present these snippets as TypeScript, TS, JavaScript, or JS.
  • Define OpenAPI x-codeSamples in the owning API route schema under apps/api/src/routes/. Never edit generated code samples only in apps/docs/reference/api/openapi.v1.yaml; pnpm run gen-swagger overwrites that file. After changing route schemas, run pnpm run gen-swagger from apps/api/, and commit the generated spec.
  • Highlight the pieces that are changing and link out to related docs.

​
SEO

  • Write with new users, search terms, and AI consumption in mind.

​
Terminology

Use these terms consistently:
  • When listing platform primitives, always put browsers first.
  • Capitalize Browser Agent and Browser Agent Platform when naming the category. Never use Web Agent.
  • Use agents in headings and body copy. AI Agent and AI Agents are allowed only in SEO or tab titles and on first-touch surfaces for non-AI-native readers.
  • Don’t lead with Search or Fetch as standalone products; browsers are the core.
  • Do not blur Agents and Stagehand. Agents is the managed API product. Stagehand is the SDK and AI browser driver.
  • Never include Director in product lists or copy. Director is sunset.
  • Automation is allowed when it describes the user’s outcome, speaks to legacy automation or RPA users, or matches demand-capture search terms.
  • Scraping, scraper, crawler, and related terms require case-by-case PMM review. They may match a customer’s use-case language, but must not appear in an H1, page title, or sidebar title.
  • Don’t position around benchmarks that can’t be defended (“best search API,” “fastest fetch”).

​
Access and identity language

  • Docs may use stealth, blocked, bot detection, anti-bot, and similar customer language only to name or explain the problem. Never use these terms to name Browserbase, the platform, or a Browserbase product.
  • Ladder from the customer’s words to Browserbase’s answer: their problem (stealth, blocked, or CAPTCHA) to Verified, then to the differentiation of Agent Identity and Web Bot Auth.
  • The only valid positioning frame for stealth is educational: identity is stronger than stealth. Never claim that Browserbase has better stealth.
  • CAPTCHA and CAPTCHA solving are allowed when describing a solution, such as “solving CAPTCHAs.”
  • Never use bot-protection vendor or product trademarks in public copy, including reCAPTCHA, hCaptcha, Turnstile, and Cloudflare.
  • Preserve exact API parameters, error messages, code identifiers, and quoted third-party text when technical accuracy requires them. Do not promote those identifiers into headings or product names.

​
Restricted use cases

Never create or approve use-case pages, demos, examples, growth hooks, SEO or SEM copy, or sales promises around:
  • Apple domains, including iTunes and the App Store
  • Entertainment, including Netflix and PlayStation
  • Banking and other financial institutions
  • Google domains without explicit approval
  • Streaming
  • Event ticketing, including Ticketmaster (travel such as flights is allowed)
  • LinkedIn
  • Mailing
Flag any copy that touches a restricted use case for PMM review before it ships.

​
Product descriptions

Use these canonical descriptions when referring to Browserbase products:
  • Browserbase: the complete platform to run agents that use the web like humans.
  • Browsers: the core; browsers that work where APIs can’t.
  • Agents: API for reusable browser agents, with no code or deployment.
  • Search and Fetch: primitives that give agents fast, token-efficient web context.
  • Functions: run code next to the browser and deploy instantly, with under 5ms latency to the browser.
  • Model Gateway: access to major models via a single Browserbase API key with unified billing.
  • Agent Identity: the attestation layer for Web Bot Auth, Signed Agents, and agent-owned accounts.
  • Verified: the customer-facing feature that gives agents reliable access when websites block automation.
  • Stagehand: the SDK and AI browser driver for browser agents.
  • Browse.sh: the open web skills catalog, accessed through the Browse CLI.