Docs styling 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.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.”
- 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. Never address the reader as “we.” The word “we” always refers to Browserbase. Flag “we” when it means 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.
Tagline
- Current: “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.
- 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:| Use this | Not this |
|---|---|
| browser agent | web agent |
| agents | AI (in most external copy) |
| headless browsers | serverless browsers |
| agent identity | stealth |
| SDK for browser agents (Stagehand) | browser automation framework |
- When listing platform primitives, always put browsers first.
- Don’t lead with Search or Fetch as standalone products — browsers are the core.
- Don’t reference automation or scraping in public-facing positioning.
- Don’t position around benchmarks that can’t be defended (“best search API,” “fastest fetch”).
- Don’t reference competitors by name in public-facing docs.
Product descriptions
Use these canonical descriptions when referring to Browserbase products:- Browserbase — the complete platform to build and deploy agents that browse and interact with the web like humans.
- Browsers — programmatic access to fleets of headless browsers with globally distributed infrastructure, isolated sessions, and built-in observability.
- Stagehand — the SDK for browser agents, combining Playwright-level control with AI primitives (act, extract, observe).
- Agent Identity — strategic partnerships and secure credential management that get agents past anti-bot systems, CAPTCHAs, and authentication walls.
- Functions — deploy and run agents on Browserbase with sub-5ms latency to the browser, zero infrastructure.
- Fetch and Search APIs — quick, token-efficient web context for agents (supporting primitives, not headline products).
- Model Gateway — access to major models via a single Browserbase API key with unified billing.
- Browse CLI — lightweight entry point for giving agents browsing capabilities without writing integration code.