Skip to content

Commit fd89dc0

Browse files
Kylejeong2Kylejeong2
committed
Add docs ownership and review rules
1 parent c343209 commit fd89dc0

5 files changed

Lines changed: 243 additions & 0 deletions

File tree

‎.cubic/docs-style-guide.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Docs style guide
2+
3+
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.
4+
5+
Apply these rules to public-facing documentation, docs navigation, README content, changelog prose, examples, and product copy.
6+
7+
## Writing style
8+
9+
Flag every violation, even minor ones.
10+
11+
- Brevity is mandatory. Every sentence must earn its place. Cut filler words: "just," "simply," "basically," "actually," "in order to," and "it should be noted that." If a sentence can be shorter without losing meaning, it must be.
12+
- Use sentence case for all titles and headings. Only capitalize the first word and proper nouns. For example, write "How Browserbase took over the world," not "How Browserbase Took Over the World." Flag title-cased headings as bugs.
13+
- Use a conversational tone, not a casual one. Text should sound natural if spoken aloud. Contractions are encouraged. Do not use slang or filler phrases like "let's dive in" or "as you can see."
14+
- Use active voice only. Flag passive voice. For example, replace "the session is created" with "Browserbase creates the session" or "you create the session."
15+
- Use second person ("you") for the reader. Always address the reader as "you," never as "we." Flag any use of "we" to mean the reader.
16+
- Require the Oxford comma. Always use a comma before "and" or "or" in a list of three or more items. Flag missing Oxford commas.
17+
- Capitalize product names, including Browserbase, Stagehand, Playwright, Functions, Search, and Identity. Default to lowercase for everything else. Flag inconsistent capitalization.
18+
- 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.
19+
- Exception: direct quotes from customers or team members in case studies may use first-person plural.
20+
21+
## Tagline
22+
23+
- Current tagline: "Agents can now browse and interact with the web like humans."
24+
- Deprecated tagline: "Autonomously read, write, and perform tasks on the web with a headless browser." Flag this if you see it.
25+
26+
## Structure and formatting
27+
28+
- Make content easy to skim. Use bullet points, break up text, and include images, videos, or tables where helpful.
29+
- Headlines should outline a clear structure and make sense on their own.
30+
- Lead with the main information. Get to the point fast, then add details. Front-load keywords for scanning.
31+
- Make customer choices and next steps obvious.
32+
33+
## Code examples
34+
35+
- Default to SDK code examples over raw API calls whenever possible.
36+
- Highlight the pieces that change and link to related docs.
37+
38+
## SEO
39+
40+
- Write with new users, search terms, and AI consumption in mind.
41+
42+
## Terminology
43+
44+
Use these terms consistently:
45+
46+
| Use this | Not this |
47+
| --- | --- |
48+
| browser agent | web agent |
49+
| agents | AI, in most external copy |
50+
| headless browsers | serverless browsers |
51+
| agent identity | stealth |
52+
| SDK for browser agents (Stagehand) | browser automation framework |
53+
| agents | agentic workflows |
54+
| browser agent platform (Browserbase) | browser automation infrastructure |
55+
56+
- When listing platform primitives, always put browsers first.
57+
- Do not lead with Search or Fetch as standalone products. Browsers are the core.
58+
- Do not reference automation or scraping in public-facing positioning.
59+
- Do not position around benchmarks that cannot be defended, such as "best search API" or "fastest fetch."
60+
- Do not reference competitors by name in public-facing docs.
61+
62+
## Product descriptions
63+
64+
Use these canonical descriptions when referring to Browserbase products:
65+
66+
- Browserbase: the complete platform to build and deploy agents that browse and interact with the web like humans.
67+
- Browsers: programmatic access to fleets of headless browsers with globally distributed infrastructure, isolated sessions, and built-in observability.
68+
- Stagehand: the SDK for browser agents, combining Playwright-level control with AI primitives (act, extract, observe).
69+
- Agent Identity: strategic partnerships and secure credential management that get agents past anti-bot systems, CAPTCHAs, and authentication walls.
70+
- Functions: deploy and run agents on Browserbase with sub-5ms latency to the browser, zero infrastructure.
71+
- Fetch and Search APIs: quick, token-efficient web context for agents. Treat these as supporting primitives, not headline products.
72+
- Model Gateway: access to major models via a single Browserbase API key with unified billing.
73+
- Browse CLI: lightweight entry point for giving agents browsing capabilities without writing integration code.

‎.cursorrules‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,3 +261,79 @@ await page2.goto("https://example2.com");
261261
await stagehand.act("click button", { page: page1 });
262262
await stagehand.extract("get title", { page: page2 });
263263
```
264+
265+
## Docs styling guide
266+
267+
Severity: blocking. Every rule in this section is mandatory. Flag violations as bugs, not suggestions. Do not approve a PR that violates any of these rules.
268+
269+
### Writing style
270+
271+
These rules are non-negotiable. Flag every violation, even minor ones.
272+
273+
- 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.
274+
- Use sentence case for all titles and headings. Only capitalize the first word and proper nouns. For example, write "How Browserbase took over the world," not "How Browserbase Took Over the World." Flag any title-cased heading as a bug.
275+
- Use a conversational tone, not a casual one. Text should sound natural if spoken aloud. Contractions are encouraged ("you'll," "it's," "don't"). Do not use slang or filler phrases like "let's dive in" or "as you can see."
276+
- Use active voice only. Flag passive voice. For example, replace "the session is created" with "Browserbase creates the session" or "you create the session."
277+
- Use second person ("you") for the reader. Always address the reader as "you," never as "we." Flag any use of "we" to mean the reader.
278+
- Require the Oxford comma. Always use a comma before "and" or "or" in a list of three or more items. Flag missing Oxford commas.
279+
- Capitalize product names, including Browserbase, Stagehand, Playwright, Functions, Search, and Identity. Default to lowercase for everything else. Flag inconsistent capitalization.
280+
- 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.
281+
- Write "Browserbase recommends," not "we recommend."
282+
- Write "Browserbase provides," not "we provide."
283+
- Write "Browserbase's infrastructure," not "our infrastructure."
284+
- Write "Browserbase supports both transports," not "we support both transports."
285+
- Exception: direct quotes from customers or team members in case studies.
286+
287+
### Tagline
288+
289+
- Current: "Agents can now browse and interact with the web like humans."
290+
- Deprecated: "Autonomously read, write, and perform tasks on the web with a headless browser." Flag this tagline if you see it.
291+
292+
### Structure and formatting
293+
294+
- Make content easy to skim. Use bullet points, break up text, and include images, videos, or tables where helpful.
295+
- Headlines should outline a clear structure and make sense on their own.
296+
- Lead with the main information. Get to the point fast, then add details. Front-load keywords for scanning.
297+
- Make customer choices and next steps obvious.
298+
299+
### Code examples
300+
301+
- Default to SDK code examples over raw API calls whenever possible.
302+
- Highlight the pieces that are changing and link to related docs.
303+
304+
### SEO
305+
306+
- Write with new users, search terms, and AI consumption in mind.
307+
308+
### Terminology
309+
310+
Use these terms consistently:
311+
312+
| Use this | Not this |
313+
| --- | --- |
314+
| browser agent | web agent |
315+
| agents | AI, in most external copy |
316+
| headless browsers | serverless browsers |
317+
| agent identity | stealth |
318+
| SDK for browser agents (Stagehand) | browser automation framework |
319+
| agents | agentic workflows |
320+
| browser agent platform (Browserbase) | browser automation infrastructure |
321+
322+
- When listing platform primitives, always put browsers first.
323+
- Do not lead with Search or Fetch as standalone products. Browsers are the core.
324+
- Do not reference automation or scraping in public-facing positioning.
325+
- Do not position around benchmarks that cannot be defended, such as "best search API" or "fastest fetch."
326+
- Do not reference competitors by name in public-facing docs.
327+
328+
### Product descriptions
329+
330+
Use these canonical descriptions when referring to Browserbase products:
331+
332+
- Browserbase: the complete platform to build and deploy agents that browse and interact with the web like humans.
333+
- Browsers: programmatic access to fleets of headless browsers with globally distributed infrastructure, isolated sessions, and built-in observability.
334+
- Stagehand: the SDK for browser agents, combining Playwright-level control with AI primitives (act, extract, observe).
335+
- Agent Identity: strategic partnerships and secure credential management that get agents past anti-bot systems, CAPTCHAs, and authentication walls.
336+
- Functions: deploy and run agents on Browserbase with sub-5ms latency to the browser, zero infrastructure.
337+
- Fetch and Search APIs: quick, token-efficient web context for agents. Treat these as supporting primitives, not headline products.
338+
- Model Gateway: access to major models via a single Browserbase API key with unified billing.
339+
- Browse CLI: lightweight entry point for giving agents browsing capabilities without writing integration code.

‎.github/CODEOWNERS‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Docs changes
2+
/packages/docs/** @kylejeong
3+
*.md @kylejeong
4+
*.mdx @kylejeong

‎claude.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,3 +297,79 @@ await page2.goto("https://example2.com");
297297
await stagehand.act("click button", { page: page1 });
298298
await stagehand.extract("get title", { page: page2 });
299299
```
300+
301+
## Docs styling guide
302+
303+
Severity: blocking. Every rule in this section is mandatory. Flag violations as bugs, not suggestions. Do not approve a PR that violates any of these rules.
304+
305+
### Writing style
306+
307+
These rules are non-negotiable. Flag every violation, even minor ones.
308+
309+
- 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.
310+
- Use sentence case for all titles and headings. Only capitalize the first word and proper nouns. For example, write "How Browserbase took over the world," not "How Browserbase Took Over the World." Flag any title-cased heading as a bug.
311+
- Use a conversational tone, not a casual one. Text should sound natural if spoken aloud. Contractions are encouraged ("you'll," "it's," "don't"). Do not use slang or filler phrases like "let's dive in" or "as you can see."
312+
- Use active voice only. Flag passive voice. For example, replace "the session is created" with "Browserbase creates the session" or "you create the session."
313+
- Use second person ("you") for the reader. Always address the reader as "you," never as "we." Flag any use of "we" to mean the reader.
314+
- Require the Oxford comma. Always use a comma before "and" or "or" in a list of three or more items. Flag missing Oxford commas.
315+
- Capitalize product names, including Browserbase, Stagehand, Playwright, Functions, Search, and Identity. Default to lowercase for everything else. Flag inconsistent capitalization.
316+
- 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.
317+
- Write "Browserbase recommends," not "we recommend."
318+
- Write "Browserbase provides," not "we provide."
319+
- Write "Browserbase's infrastructure," not "our infrastructure."
320+
- Write "Browserbase supports both transports," not "we support both transports."
321+
- Exception: direct quotes from customers or team members in case studies.
322+
323+
### Tagline
324+
325+
- Current: "Agents can now browse and interact with the web like humans."
326+
- Deprecated: "Autonomously read, write, and perform tasks on the web with a headless browser." Flag this tagline if you see it.
327+
328+
### Structure and formatting
329+
330+
- Make content easy to skim. Use bullet points, break up text, and include images, videos, or tables where helpful.
331+
- Headlines should outline a clear structure and make sense on their own.
332+
- Lead with the main information. Get to the point fast, then add details. Front-load keywords for scanning.
333+
- Make customer choices and next steps obvious.
334+
335+
### Code examples
336+
337+
- Default to SDK code examples over raw API calls whenever possible.
338+
- Highlight the pieces that are changing and link to related docs.
339+
340+
### SEO
341+
342+
- Write with new users, search terms, and AI consumption in mind.
343+
344+
### Terminology
345+
346+
Use these terms consistently:
347+
348+
| Use this | Not this |
349+
| --- | --- |
350+
| browser agent | web agent |
351+
| agents | AI, in most external copy |
352+
| headless browsers | serverless browsers |
353+
| agent identity | stealth |
354+
| SDK for browser agents (Stagehand) | browser automation framework |
355+
| agents | agentic workflows |
356+
| browser agent platform (Browserbase) | browser automation infrastructure |
357+
358+
- When listing platform primitives, always put browsers first.
359+
- Do not lead with Search or Fetch as standalone products. Browsers are the core.
360+
- Do not reference automation or scraping in public-facing positioning.
361+
- Do not position around benchmarks that cannot be defended, such as "best search API" or "fastest fetch."
362+
- Do not reference competitors by name in public-facing docs.
363+
364+
### Product descriptions
365+
366+
Use these canonical descriptions when referring to Browserbase products:
367+
368+
- Browserbase: the complete platform to build and deploy agents that browse and interact with the web like humans.
369+
- Browsers: programmatic access to fleets of headless browsers with globally distributed infrastructure, isolated sessions, and built-in observability.
370+
- Stagehand: the SDK for browser agents, combining Playwright-level control with AI primitives (act, extract, observe).
371+
- Agent Identity: strategic partnerships and secure credential management that get agents past anti-bot systems, CAPTCHAs, and authentication walls.
372+
- Functions: deploy and run agents on Browserbase with sub-5ms latency to the browser, zero infrastructure.
373+
- Fetch and Search APIs: quick, token-efficient web context for agents. Treat these as supporting primitives, not headline products.
374+
- Model Gateway: access to major models via a single Browserbase API key with unified billing.
375+
- Browse CLI: lightweight entry point for giving agents browsing capabilities without writing integration code.

‎cubic.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# yaml-language-server: $schema=https://cubic.dev/schema/cubic-repository-config.schema.json
2+
3+
version: 1
4+
5+
reviews:
6+
custom_rules:
7+
- name: Docs style guide
8+
description: Enforce Browserbase docs writing, terminology, tagline, structure, SEO, and product-description rules. Treat violations as blocking bugs on docs and Markdown changes.
9+
file_paths:
10+
- .cubic/docs-style-guide.md
11+
include:
12+
- packages/docs/**
13+
- '**/*.md'
14+
- '**/*.mdx'

0 commit comments

Comments
 (0)