From bdaa2a1b93b9b6fa8cba5635f94961b379516e63 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 3 Mar 2026 10:30:24 +0100 Subject: [PATCH 1/6] docs: add grammar rules and refine shared style guide Extract grammar mechanics into a new grammar-rules.md file covering hyphenation, contractions, e.g./i.e., numbers, list punctuation, and brand spelling. Refocus writing-style.md on voice and tone by removing formatting sections that duplicate content-standards.md. Add article usage rules for Apify products, crawler/scraper capitalization, and US vs British English patterns to the shared style guide files. Co-Authored-By: Claude Opus 4.6 --- .claude/rules/content-standards.md | 30 +++- .claude/rules/grammar-rules.md | 176 ++++++++++++++++++++++++ .claude/rules/terminology.md | 31 ++++- .claude/rules/writing-style.md | 213 ++++------------------------- 4 files changed, 258 insertions(+), 192 deletions(-) create mode 100644 .claude/rules/grammar-rules.md diff --git a/.claude/rules/content-standards.md b/.claude/rules/content-standards.md index fc22493aa7..506d245d35 100644 --- a/.claude/rules/content-standards.md +++ b/.claude/rules/content-standards.md @@ -79,7 +79,7 @@ slug: /academy/tutorials/web-scraper | How Do I Start? | How do I start? | Capitalize "I" in questions | | Understanding Request Queues | Understand request queues | Lowercase feature names | | Enable Standby Mode | Enable standby mode | Lowercase mode names | -| Access The Apify Console | Access the Apify Console | "Apify Console" stays capitalized (product) | +| Access The Apify Console | Access Apify Console | "Apify Console" stays capitalized (product), no "the" | | Run Your First Actor | Run your first Actor | "Actor" capitalized, "your" lowercase | | Manage Node Modules | Manage node modules | Lowercase generic terms | | Step 1: install the dependencies | Step 1: Install the dependencies | Capitalize after colon (starts new clause) | @@ -97,12 +97,10 @@ slug: /academy/tutorials/web-scraper ### Hierarchy -Follow proper heading hierarchy: H1 → H2 → H3. Never skip levels. +Follow proper heading hierarchy: H2 → H3 → H4. Never skip levels. (H1 is the page title, set in front matter) ```markdown -# Page Title (H1 - only one per page, usually from front matter) - -## Main Section (H2) +## Main section (H2) ### Subsection (H3) @@ -147,6 +145,10 @@ Use backticks for inline code: - Variable names: `API_TOKEN`, `userId` - Code values: `true`, `null`, `"string"` +### Em dashes + +Don't use em dashes (—). Use hyphen with spaces ( - ) instead. + ## Admonitions Use Docusaurus admonitions for important information. **All admonitions MUST have titles.** @@ -310,6 +312,21 @@ can crawl websites and extract text content. Subsequent mentions: Just the name, no link needed. +### Tool mentions + +When mentioning tools, languages, or external resources, link to their official site: + +| Avoid | Prefer | +|-------|--------| +| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | + +### Trim link filler + +| Avoid | Prefer | +|-------|--------| +| visit the Docker Hub tags page | visit Docker Hub | +| check out the official docs | check the documentation | + ## Images ### Alt text @@ -369,12 +386,15 @@ platform/ - Format: Month Day, Year - Example: August 5, 2024 - Never: 5.8.2024 or 2024-08-05 in prose (ISO format OK in code) +- No ordinal suffixes: "August 5" not "August 5th" +- No abbreviated months: "January" not "Jan" ### Time - Format: 12-hour with space before AM/PM - Example: 5 PM, 11:30 AM - Uppercase: PM (not pm or p.m.) +- Never use periods: "5 PM" not "5 p.m." ## Parallel structure diff --git a/.claude/rules/grammar-rules.md b/.claude/rules/grammar-rules.md new file mode 100644 index 0000000000..b6b1596d17 --- /dev/null +++ b/.claude/rules/grammar-rules.md @@ -0,0 +1,176 @@ +--- +description: Grammar mechanics and punctuation rules for Apify documentation +globs: ["sources/**/*.md", "sources/**/*.mdx"] +alwaysApply: true +--- + +# Grammar rules + +Grammar mechanics and punctuation rules for all Apify documentation. These complement the writing style and terminology guides. + +## Compound adjective hyphenation + +Hyphenate compound adjectives before nouns. Don't hyphenate after nouns or with -ly adverbs. + +| Avoid | Prefer | Rule | +|-------|--------|------| +| real time dashboard | real-time dashboard | Hyphenate before noun | +| battle tested solution | battle-tested solution | Hyphenate before noun | +| the dashboard updates in real-time | the dashboard updates in real time | Don't hyphenate after noun | +| a fully-automated process | a fully automated process | Don't hyphenate -ly adverbs | +| a well known library | a well-known library | Hyphenate before noun | +| the library is well-known | the library is well known | Don't hyphenate after noun | + +## Contractions + +Use contractions for a natural, conversational tone (don't, can't, you'll, it's, won't). Be consistent within each page. + +Imperative warnings without contractions are fine for emphasis: + +| Context | Example | +|---------|---------| +| General docs | "You don't need to install anything." | +| Critical warning | "Do not delete production data." | +| Instructions | "If the build doesn't start, check the logs." | + +## "etc." usage + +Always place a comma before "etc." Never combine "such as" with "etc." - they serve the same limiting function. + +| Avoid | Prefer | +|-------|--------| +| such as Node.js, Python, etc. | such as Node.js and Python | +| formats like JSON, YAML etc. | formats like JSON, YAML, etc. | +| | Supports JSON, YAML, XML, and more. | + +Prefer "and more" as an alternative to "etc." in running prose. + +## "e.g." and "i.e." formatting + +Place a comma before "e.g." and "i.e." but no comma after (Apify house style). Don't start sentences with "e.g." or "i.e." + +| Avoid | Prefer | +|-------|--------| +| Use a runtime, e.g., Node.js | Use a runtime, e.g. Node.js | +| Use a runtime e.g. Node.js | Use a runtime, e.g. Node.js | +| E.g. you can use Playwright | For example, you can use Playwright | +| I.e. it runs on the server | That is, it runs on the server | + +- **e.g.** means "for example" - introduces a partial list +- **i.e.** means "that is" - restates or clarifies + +## "such as" comma rules + +Use a comma before "such as" when the information is nonrestrictive (extra, removable). Omit the comma when restrictive (narrows the meaning). + +| Type | Example | Test | +|------|---------|------| +| Nonrestrictive | "Apify supports many languages, such as JavaScript and Python." | Remove "such as..." and the sentence still makes sense. | +| Restrictive | "Languages such as JavaScript and Python are supported." | Removing "such as..." changes the meaning. | + +**Removability test:** If the "such as" clause can be removed without changing the core meaning, add a comma. + +## "a" vs "an" + +Base the article on sound, not spelling: + +| Example | Reason | +|---------|--------| +| a URL | Starts with "yoo-" sound | +| an API | Starts with "ay-" sound | +| a universal solution | Starts with "yoo-" sound | +| an hour | Silent "h" | +| an HTML page | Starts with "aitch-" sound | +| a JSON file | Starts with "jay-" sound | +| an SQL query | Starts with "ess-" sound | +| a UUID | Starts with "yoo-" sound | + +## Numbers in prose + +Spell out one through nine. Use digits for 10 and above. + +Always use digits for: + +- Measurements: 5 GB, 3 seconds, 2 CPUs +- Versions: version 18, version 3.0 +- Percentages: 5%, 100% +- Prices: $5, $1,000 +- Technical values: 0, 1, port 8080 + +When mixing ranges in the same sentence, use digits for both: + +| Avoid | Prefer | +|-------|--------| +| between three and 15 retries | between 3 and 15 retries | +| from one to 100 results | from 1 to 100 results | + +## Number abbreviations + +Use M for million, B for billion, k for thousand. + +| Context | Format | +|---------|--------| +| Tight spaces, tables | 5M requests, 2.5k users | +| First mentions, emphasis | 5 million requests per day | +| Prose | The platform handles over 10 billion requests | + +## List punctuation + +Full sentences get periods. Fragments get no punctuation. Don't mix within a list. + +**Full sentences (periods):** + +```markdown +- The Actor starts and initializes the browser. +- It navigates to the target URL and waits for the page to load. +- Results are saved to the default dataset. +``` + +**Fragments (no punctuation):** + +```markdown +- Browser initialization +- Page navigation +- Data storage +``` + +Never use commas or semicolons at the end of list items. + +## Ampersand usage + +Use "and" in prose. Reserve "&" for brand names, UI labels, event titles, and tight spaces (tables, headings with space constraints). + +| Avoid | Prefer | +|-------|--------| +| scraping & crawling | scraping and crawling | +| AT and T | AT&T | + +## Gender-neutral language + +Use "they/their" as a singular pronoun when the person's name isn't specified. + +| Avoid | Prefer | +|-------|--------| +| When a user starts his Actor | When a user starts their Actor | +| he/she can configure | they can configure | +| Each developer should check his or her settings | Each developer should check their settings | + +## Tool and brand name spelling + +Use the exact official spelling for tools and brand names: + +| Incorrect | Correct | +|-----------|---------| +| Javascript | JavaScript | +| Typescript | TypeScript | +| NodeJS, Node.JS | Node.js | +| Github | GitHub | +| Chatgpt | ChatGPT | +| N8n, N8N | n8n | +| Mongodb | MongoDB | +| Postgresql, Postgres | PostgreSQL | +| Jquery | jQuery | +| Wordpress | WordPress | +| Elasticsearch | Elasticsearch | +| VSCode, VS code | VS Code | +| DockerFile, dockerfile | Dockerfile | diff --git a/.claude/rules/terminology.md b/.claude/rules/terminology.md index 484c0c7b61..1abd376072 100644 --- a/.claude/rules/terminology.md +++ b/.claude/rules/terminology.md @@ -20,6 +20,20 @@ Always capitalize these Apify product names: - **Apify CLI** (never "Apify cli") - **Apify API** (never "Apify api") +## Article usage with Apify products + +Some products take "the", others don't. Follow this table: + +| Product | Article | Correct | Incorrect | +|---------|---------|---------|-----------| +| Apify Console | No "the" | Log into Apify Console | Log into the Apify Console | +| Apify Store | No "the" | Find Actors in Apify Store | Find Actors in the Apify Store | +| Apify SDK | Requires "the" | Build with the Apify SDK | Build with Apify SDK | +| Apify CLI | Requires "the" | Install the Apify CLI | Install Apify CLI | +| Apify API | Requires "the" | Call the Apify API | Call Apify API | +| Apify Proxy | No "the" | Connect through Apify Proxy | Connect through the Apify Proxy | +| the Apify platform | Always "the" | Deploy on the Apify platform | Deploy on Apify platform | + ## Platform terms Use lowercase for general platform references (include "the"): @@ -91,12 +105,16 @@ The `Apify.main()` function is deprecated. Use `Actor.main()` instead. ### Actor names -When referring to specific Actors in the Apify Store: +When referring to specific Actors in Apify Store: - First mention: Full name with link, capitalized - Example: `[Website Content Crawler](https://apify.com/apify/website-content-crawler)` - Subsequent mentions: Just the name, no link needed - Example: `Website Content Crawler can extract text content.` +- No "the" before Actor names - treat them like proper nouns (person names) + - Correct: "Website Content Crawler can perform deep crawls." + - Incorrect: "The Website Content Crawler can perform deep crawls." + - Exception: "the" is OK when the Actor name modifies a following noun: "Use the Website Content Crawler Actor." ### Version numbers @@ -104,6 +122,17 @@ When referring to specific Actors in the Apify Store: - Example: "Node.js version 22" (not "Node.js v22" or "Node.js ver 22") - Exception: Tags and code can use abbreviations (`node:22`, `v3.0.0`) +### Crawler and scraper capitalization + +Keep "crawler" and "scraper" lowercase as generic terms. Capitalize only when part of a proper Actor name. + +| Context | Example | +|---------|---------| +| Generic term | "Use a web crawler to extract data." | +| Actor name | "Website Content Crawler can extract text content." | +| Generic term | "Build a custom scraper with Crawlee." | +| Actor name | "Google Search Scraper returns structured results." | + ### Acronyms and abbreviations First use: Spell out with acronym in parentheses diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md index 4ca1968e88..9d80e1906b 100644 --- a/.claude/rules/writing-style.md +++ b/.claude/rules/writing-style.md @@ -34,6 +34,19 @@ Don't use "Learn" for pure reference documentation - it sets tutorial expectatio Use "analyze" not "analyse", "color" not "colour". +Common US vs British English patterns: + +| British | US (preferred) | +| ------- | -------------- | +| -ise (organise) | -ize (organize) | +| -our (colour) | -or (color) | +| -re (centre) | -er (center) | +| -ogue (catalogue) | -og (catalog) | +| programme | program | +| grey | gray | +| travelled | traveled | +| licence (noun) | license | + ### Imperative tone Use direct instructions, not soft recommendations: @@ -70,129 +83,21 @@ Use active voice. Avoid gendered terms. Don't use directional language ("left/ri | He can configure his settings | You can configure your settings | | Click the button on the left | Click the **Settings** button | -## Formatting - -### Headings - -**Sentence case only.** No title case. - -Common mistakes: Capitalizing articles (the, a, an), prepositions (to, with, from), and conjunctions (and, or, but). - -| Avoid (Title Case) | Prefer (Sentence case) | -| ------------------ | ---------------------- | -| Store And Manage Data | Store and manage data | -| Use The Apify SDK | Use the Apify SDK | -| Connect To Google Sheets | Connect to Google Sheets | -| Configure GitHub Actions | Configure GitHub Actions | -| How Do I Start? | How do I start? | - -**Preserve proper nouns and acronyms:** Apify products (Actors, Console, Proxy), external tools (GitHub, Docker, Playwright), and acronyms (API, SDK, CLI) stay capitalized. - -**Capitalize after colons:** When a colon introduces a complete clause or instruction, capitalize the first word after it. - -| Avoid | Prefer | -| ----- | ------ | -| Step 1: install the dependencies | Step 1: Install the dependencies | -| Option 2: use the alternative | Option 2: Use the alternative | - -**No gerunds (-ing forms).** Use noun phrases or imperatives. - -| Avoid | Prefer | -| ----------------------------- | -------------------------- | -| Finding available tags | Available tags | -| Getting started with Actors | Get started with Actors | -| Understanding the API | API overview | -| Setting up your environment | Set up your environment | -| Using Docker containers | Use Docker containers | -| Building your first Actor | Build your first Actor | -| Running the scraper | Run the scraper | -| Extending the base image | Extend the base image | - -Rationale: Noun-phrase headings are more scannable and search-friendly (Microsoft style guide). - -### Bold - -**Do use bold for:** - -- UI elements (buttons, menus, fields): Click the **Actors** button -- Critical warnings or key terms - -**Don't use bold for:** - -- List introductions -- Code block introductions -- Section labels when context is clear - -| Avoid | Prefer | -| ------------------------------- | ----------------------------- | -| **Examples:** | Examples: | -| **In your Dockerfile**, use... | In your `Dockerfile`, use... | - -Bold for UI elements helps users scan for clickable items. Bold for structure creates visual noise. - -### Italics - -Use italics for emphasis and introducing new terms: - -| Use case | Example | -| ------------------------ | --------------------------------------------- | -| New term introduction | An *Actor* is a serverless program... | -| Emphasis | This step is *required* for the Actor to work | - -### List types - -**Numbered lists** - Sequential steps where order matters -**Bullet points** - Non-sequential items, features, options - -In numbered lists, use `1.` for all items (not sequential numbers). Easier to maintain: - -```markdown -1. First step -1. Second step -1. Third step -``` - -### Parallel structure - -All items in a list must follow the same grammatical pattern: - -```markdown -# Avoid - mixed patterns -1. Reproducibility - your builds behave the same -1. Predictability - you know which version -1. Easier to track down issues - -# Prefer - consistent pattern -1. Reproducibility - Your builds behave the same way -1. Predictability - You know exactly which version you're running -1. Debugging - Version-specific issues are easier to track down -``` +### Avoid "our" -### Em dashes +Replace "our" with "the" or "Apify" to keep docs product-focused rather than company-focused. -**Don't use em dashes (—).** LLMs overuse them. Use hyphen with spaces ( - ) instead. - -### Admonitions - -Use Docusaurus admonitions for important information: - -| Type | Use for | -| ------------ | ------------------------------------------- | -| `:::note` | General callouts | -| `:::tip` | Helpful suggestions | -| `:::info` | Background context | -| `:::caution` | Warnings about gotchas | -| `:::danger` | Critical warnings that could cause issues | - -**All admonitions require titles.** Use 2-3 words that are scannable and summarize the content. +| Avoid | Prefer | +| -------------------- | ------------------------- | +| our team | the Apify team | +| our platform | the Apify platform | +| our API | the Apify API | +| our documentation | the Apify documentation | -| Avoid | Prefer | -| --------------------------------------- | -------------------------- | -| `:::note Note` | `:::note Actor versions` | -| `:::caution Be careful when deleting` | `:::caution Data loss` | -| `:::tip` (no title) | `:::tip Performance` | +Acceptable uses of "our" - direct team actions or invitations: -Prefer admonitions over block quotes for highlighted content. +- "We're excited to announce..." (team action) +- "Join our webinar" (direct invitation) ## Grammar @@ -212,74 +117,9 @@ Always use the serial comma: | ---------------------------- | -------------------------------- | | pencil, eraser and notebook | pencil, eraser, and notebook | -### "the" before products - -Use "the" before "Apify platform", "Apify SDK", etc. - -| Avoid | Prefer | -| -------------------- | ------------------------- | -| I use Apify platform | I use the Apify platform | - -## Terminology - -See `terminology.md` for complete Apify-specific terminology and capitalization rules. - -## Links - -### Action-oriented text - -| Avoid | Prefer | -| --------------------------------- | --------------------------------------- | -| [actor-node-playwright tags](url) | [View actor-node-playwright tags](url) | -| See the [documentation](url) | [Read the documentation](url) | - -### Accessible link text - -Use descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. - -| Avoid | Prefer | -| ---------------------------------- | ----------------------------------------- | -| `[Click here](url)` to learn more | `[Learn about Actor pricing](url)` | -| Read more about it `[here](url)` | Read the `[Actor development guide](url)` | - -### Make tool mentions navigable - -When mentioning tools, languages, or external resources, link them to help readers explore: - -| Avoid | Prefer | -| ----------------------------------- | ----------------------------------------------------------- | -| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | - -### Trim filler words - -| Avoid | Prefer | -| ------------------------------ | --------------------- | -| visit the Docker Hub tags page | visit Docker Hub | -| check out the official docs | check the documentation | - -### Actor references - -First mention: Actor name with link, capitalized. - -```markdown -[Website Content Crawler](https://apify.com/apify/website-content-crawler) -can crawl websites and extract text content. -``` - -## Code Examples - -- Use backticks for file names, commands, config keys -- Prefer complete, runnable examples -- Add comments only when code isn't self-explanatory -- Match versions in examples (e.g., Dockerfile tag matches package.json version) - -## Numbers & Formatting +## Formatting, links, and code -- Thousands: comma separator ($1,000) -- Decimals: period ($9.8) -- Money: symbol before amount ($49, not 49$) -- Dates: August 5, 2024 (never 5.8.2024) -- Time: 5 PM (space before, uppercase) +See `content-standards.md` for all formatting rules (headings, bold, code, admonitions, lists, links, images, numbers). See `grammar-rules.md` for grammar mechanics (hyphenation, contractions, e.g./i.e., list punctuation). ## Common Mistakes @@ -294,6 +134,7 @@ Patterns to avoid: - Missing "the" before "Apify platform" - Sales language ("ultimate", "cutting-edge", "supercharge") - Vague claims without numbers +- Corrupted em dash characters (`â€"`) - always fix these encoding artifacts ## Reference From f7e492b3fd842702f7280f5543c1b9f0a7ce11b1 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 3 Mar 2026 11:06:06 +0100 Subject: [PATCH 2/6] docs: update repo-specific config for grammar rules file Add grammar-rules.md references to README, instructions, quality checklist, and review skill. Update file descriptions across all config files to reflect the new separation of concerns. Restructure review-docs skill to use subagent delegation for style compliance checks against individual rules files. Co-Authored-By: Claude Opus 4.6 --- .claude/README.md | 18 ++++--- .claude/instructions.md | 11 ++-- .claude/rules/quality-standards.md | 2 + .claude/skills/review-docs/SKILL.md | 84 ++++++++++++++++++----------- 4 files changed, 71 insertions(+), 44 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index 2744cd0c14..37cb50b2a1 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -9,10 +9,11 @@ This directory contains Claude Code configuration for the Apify documentation re ├── README.md # This file - Quick start guide ├── instructions.md # Main instructions for Claude Code ├── rules/ # Canonical standards (auto-loaded) -│ ├── writing-style.md # Language, tone, grammar -│ ├── content-standards.md # Formatting, front matter, code -│ ├── terminology.md # Apify-specific terms +│ ├── writing-style.md # Prose voice and tone +│ ├── content-standards.md # Formatting and structure +│ ├── terminology.md # Product names and capitalization │ ├── file-organization.md # Naming conventions +│ ├── grammar-rules.md # Grammar mechanics, punctuation, numbers, brand spelling │ └── quality-standards.md # Quality checklist └── skills/ # Reusable skills for common tasks ├── doc-write/ # Documentation writing skill @@ -73,11 +74,12 @@ Use /review-docs skill to review sources/platform/[file-name].md All documentation standards are in `.claude/rules/` (auto-loaded): -1. **`writing-style.md`** - Language, tone, grammar, headings, word choice -2. **`content-standards.md`** - Front matter, formatting, code examples, links, images -3. **`terminology.md`** - Apify-specific capitalization and product names -4. **`file-organization.md`** - File naming and directory structure -5. **`quality-standards.md`** - Comprehensive pre-submission checklist +1. **`writing-style.md`** - Prose voice and tone +1. **`content-standards.md`** - Formatting and structure +1. **`terminology.md`** - Product names and capitalization +1. **`grammar-rules.md`** - Grammar mechanics, punctuation, numbers, brand spelling +1. **`file-organization.md`** - File naming and directory structure +1. **`quality-standards.md`** - Complete quality checklist Also reference: diff --git a/.claude/instructions.md b/.claude/instructions.md index 5d8abab214..b72582b64f 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -6,11 +6,12 @@ Read `AGENTS.md` first - it is the single source of truth for project architectu Detailed documentation standards are auto-loaded from `.claude/rules/`: -- `writing-style.md` - Language, tone, grammar, headings -- `content-standards.md` - Front matter, formatting, code examples, links, images -- `terminology.md` - Apify product capitalization -- `file-organization.md` - Naming and directory structure -- `quality-standards.md` - Pre-submission checklist +- `writing-style.md` - Prose voice and tone +- `content-standards.md` - Formatting and structure +- `terminology.md` - Product names and capitalization +- `grammar-rules.md` - Grammar mechanics, punctuation, numbers, brand spelling +- `file-organization.md` - File naming and directory structure +- `quality-standards.md` - Complete quality checklist These rules expand on the standards in `AGENTS.md` with detailed examples and tables. diff --git a/.claude/rules/quality-standards.md b/.claude/rules/quality-standards.md index dff1f031dc..85259df615 100644 --- a/.claude/rules/quality-standards.md +++ b/.claude/rules/quality-standards.md @@ -62,6 +62,8 @@ Before submitting documentation, verify: - [ ] Platform terms use lowercase with "the" (the Apify platform, not Platform) - [ ] Feature terms use lowercase (task, schedule, dataset, not Task/Schedule/Dataset) - [ ] Word choice is precise (legacy vs alternative vs deprecated used correctly) +- [ ] Article usage correct per **terminology.md** (no "the" before Apify Console/Store/Proxy; "the" before SDK/CLI/API) +- [ ] Grammar mechanics follow **grammar-rules.md** (hyphenation, contractions, e.g./i.e., numbers, list punctuation) ### Code examples diff --git a/.claude/skills/review-docs/SKILL.md b/.claude/skills/review-docs/SKILL.md index d5185d444e..97e3d4c004 100644 --- a/.claude/skills/review-docs/SKILL.md +++ b/.claude/skills/review-docs/SKILL.md @@ -13,58 +13,80 @@ Review documentation for compliance with Apify style guide, quality standards, a **CRITICAL**: Verify you're reviewing the latest version of the file. If reviewing a PR, confirm the branch is up to date. +## Standards reference + +Review compliance against all standards in `.claude/rules/`: + +- `writing-style.md` - Prose voice and tone +- `content-standards.md` - Formatting and structure +- `terminology.md` - Product names and capitalization +- `grammar-rules.md` - Grammar mechanics and punctuation +- `quality-standards.md` - Complete quality checklist +- `file-organization.md` - File naming and directory structure + +## Review process + ### Step 2: Run automated checks ```bash npm run lint:md # Markdownlint - Markdown syntax/formatting npm run lint:code # ESLint - Code linting -vale sync # Vale - Download styles (first time only) -vale "path/to/file.md" --minAlertLevel=error # Vale - Prose style check ``` -### Step 3: Manual review +## Review checklist + +### Style compliance (delegated) + +For each rules file, launch a subagent to check the reviewed content against that file's standards. The subagent reads the rules file directly, so the review always uses the latest rules. + +Check content compliance against: -Go through the checklist below, noting issues found. +1. `writing-style.md` - voice, tone, language patterns +1. `content-standards.md` - formatting, front matter, headings, code, links, images +1. `terminology.md` - product names, article usage, feature terms +1. `grammar-rules.md` - hyphenation, punctuation, numbers, brand spelling -#### Writing quality +Each subagent should return a list of violations with line numbers and suggested fixes. -- [ ] Headings: Sentence case, no gerunds ("Create" not "Creating") -- [ ] Bold: ONLY for UI elements (not emphasis) -- [ ] Language: US English, active voice, inclusive, simple -- [ ] Terminology: Matches `.claude/rules/terminology.md` +### Content review (manual) -#### Front matter +These aspects require judgment and aren't covered by the rules files: -- [ ] `title` - Sentence case, simple present tense -- [ ] `description` - 140-160 chars, value-focused (not feature list) -- [ ] `slug` - Matches file path -- [ ] `sidebar_position` - Appropriate numbering +- [ ] **Content structure** - Clear introduction, logical progression, summary/next steps +- [ ] **Heading hierarchy** - H2 → H3 → H4, no skipped levels +- [ ] **Technical accuracy** - Code examples tested, API endpoints current, no deprecated features +- [ ] **Completeness** - Prerequisites listed, all steps included, edge cases addressed +- [ ] **Content-type checks** + - **Tutorials**: Clear learning objectives, sequential numbered steps, verification at each step + - **API docs**: All parameters documented, code samples in JS and Python, error responses + - **Reference pages**: Comprehensive parameter tables, default values, type information +- [ ] **Accessibility** - Proper heading hierarchy, descriptive link text, image alt text +- [ ] **SEO** - Descriptive title, meta description 140-160 chars, internal linking -#### Content structure +## How to review -- [ ] Clear introduction -- [ ] Proper heading hierarchy (H1 → H2 → H3, no skips) -- [ ] Logical topic progression -- [ ] Summary/next steps at end -- [ ] Related content linked +### Step 1: Run automated checks -#### Formatting +```bash +npm run lint:md # Markdownlint - Markdown syntax/formatting +npm run lint:code # ESLint - Code linting +``` -- [ ] Code examples: Complete, runnable, language tag specified -- [ ] Links: Descriptive text (not "click here"), internal use relative paths -- [ ] Images: Meaningful alt text, light theme, red indicators -- [ ] Admonitions: Must have title, appropriate type, max 2-3 per page -- [ ] Code review scope: Comments and obvious mistakes only (not full review) +### Step 2: Check style compliance -#### Content-type checks +For each of the rules files listed above, review the content against that file's standards. Use a subagent per file to read the rules and check compliance. Collect all violations. -- **Tutorials**: Clear learning objectives, prerequisites, numbered steps, summary -- **API docs**: Operation IDs follow conventions, parameters documented, code samples included -- **Reference pages**: Parameter tables, default values, type information +### Step 3: Content review + +Go through the manual content review checklist above. These require human/AI judgment about structure, accuracy, and completeness. ### Step 4: Provide feedback -Format your review using the template in `references/review-format.md`. +Format your review using the output template below. + +```markdown +## Documentation review: [File name] +``` ## Examples From 2d3abbad9b89921eb43d1849d25b60af7f93357f Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 4 Mar 2026 15:46:25 +0100 Subject: [PATCH 3/6] docs: update style guide rules and add argument hints for skills --- .claude/README.md | 3 ++- .claude/rules/content-standards.md | 6 ------ .claude/rules/file-organization.md | 6 ------ .claude/rules/grammar-rules.md | 7 ------- .claude/rules/quality-standards.md | 6 ------ .claude/rules/terminology.md | 6 ------ .claude/rules/writing-style.md | 6 ------ .claude/skills/api-doc/SKILL.md | 1 + .claude/skills/doc-write/SKILL.md | 1 + .claude/skills/review-docs/SKILL.md | 28 +++------------------------- .claude/skills/tutorial/SKILL.md | 1 + 11 files changed, 8 insertions(+), 63 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index 37cb50b2a1..0953e5590c 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -94,6 +94,7 @@ Before submitting: ```bash npm run lint:md # Check markdown npm run lint:code # Check code +vale "path/to/file.md" --minAlertLevel=error # Check prose style npm start # Preview changes npm test # Validate API specs ``` @@ -103,7 +104,7 @@ npm test # Validate API specs 1. **Read `AGENTS.md` first** - Vendor-agnostic documentation standards 2. **Check `.claude/rules/`** - Auto-loaded standards for writing, formatting, terminology 3. **Use the appropriate skill** - Designed for specific documentation tasks -4. **Run linters before committing** - `npm run lint:md` and `npm run lint:code` +4. **Run linters before committing** - `npm run lint:md`, `npm run lint:code`, and `vale` 5. **Review before submit** - Use `/review-docs` skill for final checks ## Need help? diff --git a/.claude/rules/content-standards.md b/.claude/rules/content-standards.md index 506d245d35..011bcc5431 100644 --- a/.claude/rules/content-standards.md +++ b/.claude/rules/content-standards.md @@ -1,9 +1,3 @@ ---- -description: Standard formatting rules for all Apify documentation -globs: ["sources/**/*.md", "sources/**/*.mdx"] -alwaysApply: true ---- - # Content Standards Canonical formatting standards for all Apify documentation. These rules ensure consistency across platform docs, academy tutorials, and API references. diff --git a/.claude/rules/file-organization.md b/.claude/rules/file-organization.md index 55cee71f1f..b1523a0901 100644 --- a/.claude/rules/file-organization.md +++ b/.claude/rules/file-organization.md @@ -1,9 +1,3 @@ ---- -description: File naming conventions and directory structure standards -globs: ["sources/**/*"] -alwaysApply: true ---- - # File Organization Rules ## Naming conventions diff --git a/.claude/rules/grammar-rules.md b/.claude/rules/grammar-rules.md index b6b1596d17..d3d36f79ca 100644 --- a/.claude/rules/grammar-rules.md +++ b/.claude/rules/grammar-rules.md @@ -1,9 +1,3 @@ ---- -description: Grammar mechanics and punctuation rules for Apify documentation -globs: ["sources/**/*.md", "sources/**/*.mdx"] -alwaysApply: true ---- - # Grammar rules Grammar mechanics and punctuation rules for all Apify documentation. These complement the writing style and terminology guides. @@ -171,6 +165,5 @@ Use the exact official spelling for tools and brand names: | Postgresql, Postgres | PostgreSQL | | Jquery | jQuery | | Wordpress | WordPress | -| Elasticsearch | Elasticsearch | | VSCode, VS code | VS Code | | DockerFile, dockerfile | Dockerfile | diff --git a/.claude/rules/quality-standards.md b/.claude/rules/quality-standards.md index 85259df615..4984328c83 100644 --- a/.claude/rules/quality-standards.md +++ b/.claude/rules/quality-standards.md @@ -1,9 +1,3 @@ ---- -description: Content quality checklist and review standards -globs: ["sources/**/*.md", "sources/**/*.mdx"] -alwaysApply: true ---- - # Quality Standards Comprehensive quality checklist for all Apify documentation. Use this before submitting any content for review. diff --git a/.claude/rules/terminology.md b/.claude/rules/terminology.md index 1abd376072..fdbadec0e2 100644 --- a/.claude/rules/terminology.md +++ b/.claude/rules/terminology.md @@ -1,9 +1,3 @@ ---- -description: Official Apify product and technical terminology -globs: ["sources/**/*.md", "sources/**/*.mdx", "apify-api/**/*.yaml"] -alwaysApply: true ---- - # Apify Terminology Official capitalization and usage rules for Apify-specific terms. Use these exact forms throughout all documentation. diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md index 9d80e1906b..0dc07e5928 100644 --- a/.claude/rules/writing-style.md +++ b/.claude/rules/writing-style.md @@ -1,9 +1,3 @@ ---- -description: Comprehensive writing style rules for Apify documentation -globs: ["sources/**/*.md", "sources/**/*.mdx"] -alwaysApply: true ---- - # Apify Documentation Writing Style Instructions for AI assistants writing Apify documentation. Based on Apify style guide and technical writer feedback. diff --git a/.claude/skills/api-doc/SKILL.md b/.claude/skills/api-doc/SKILL.md index f6fb407769..1748f439c0 100644 --- a/.claude/skills/api-doc/SKILL.md +++ b/.claude/skills/api-doc/SKILL.md @@ -1,6 +1,7 @@ --- name: api-doc description: Create or update OpenAPI specifications and API documentation for Apify endpoints. Use when user says "add API endpoint", "create OpenAPI spec", "document this endpoint", "add code samples for API", "update API docs", or "api-doc". Handles OpenAPI YAML, schemas, code samples, and operation IDs. +argument-hint: endpoint-path --- # API documentation diff --git a/.claude/skills/doc-write/SKILL.md b/.claude/skills/doc-write/SKILL.md index 55081aa480..b0ea79a396 100644 --- a/.claude/skills/doc-write/SKILL.md +++ b/.claude/skills/doc-write/SKILL.md @@ -1,6 +1,7 @@ --- name: doc-write description: Write or edit Apify documentation pages following the style guide. Use when user says "write docs for", "create a new page", "document this feature", "add documentation about", "edit this doc page", or "write a guide for [topic]". Handles platform docs, guides, and reference pages with proper formatting and structure. +argument-hint: topic --- # Documentation writer diff --git a/.claude/skills/review-docs/SKILL.md b/.claude/skills/review-docs/SKILL.md index 97e3d4c004..e5ebf53baf 100644 --- a/.claude/skills/review-docs/SKILL.md +++ b/.claude/skills/review-docs/SKILL.md @@ -1,6 +1,7 @@ --- name: review-docs description: Review Apify documentation for style guide compliance, quality standards, and best practices. Use when user says "review this doc", "check this page", "audit documentation", "review before PR", "is this ready to publish", or "review-docs". Runs automated checks and manual review against Apify style guide. +argument-hint: file-path --- # Documentation review @@ -31,6 +32,7 @@ Review compliance against all standards in `.claude/rules/`: ```bash npm run lint:md # Markdownlint - Markdown syntax/formatting npm run lint:code # ESLint - Code linting +vale "path/to/file.md" --minAlertLevel=error # Vale - Prose and style ``` ## Review checklist @@ -63,31 +65,6 @@ These aspects require judgment and aren't covered by the rules files: - [ ] **Accessibility** - Proper heading hierarchy, descriptive link text, image alt text - [ ] **SEO** - Descriptive title, meta description 140-160 chars, internal linking -## How to review - -### Step 1: Run automated checks - -```bash -npm run lint:md # Markdownlint - Markdown syntax/formatting -npm run lint:code # ESLint - Code linting -``` - -### Step 2: Check style compliance - -For each of the rules files listed above, review the content against that file's standards. Use a subagent per file to read the rules and check compliance. Collect all violations. - -### Step 3: Content review - -Go through the manual content review checklist above. These require human/AI judgment about structure, accuracy, and completeness. - -### Step 4: Provide feedback - -Format your review using the output template below. - -```markdown -## Documentation review: [File name] -``` - ## Examples Example 1: Pre-PR review @@ -97,6 +74,7 @@ User says: "Review sources/platform/actors/running.md before I submit" Actions: 1. Read the file 1. Run `npx markdownlint "sources/platform/actors/running.md"` +1. Run `vale "sources/platform/actors/running.md" --minAlertLevel=error` 1. Check against review checklist 1. Output structured review with strengths, issues, and priority fixes diff --git a/.claude/skills/tutorial/SKILL.md b/.claude/skills/tutorial/SKILL.md index da9b538fdf..b33e40917e 100644 --- a/.claude/skills/tutorial/SKILL.md +++ b/.claude/skills/tutorial/SKILL.md @@ -1,6 +1,7 @@ --- name: tutorial description: Create structured tutorials for Apify Academy or Platform documentation. Use when user says "create a tutorial", "write a tutorial", "build a step-by-step guide", "convert this guide into a tutorial", or "tutorial for [topic]". Handles tutorial structure, learning objectives, prerequisites, step-by-step instructions, code examples, and troubleshooting sections. +argument-hint: topic --- # Tutorial creator From b85d50e63cbc6104303a4cc47a9502eee667373a Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 4 Mar 2026 16:03:43 +0100 Subject: [PATCH 4/6] docs: update README and instructions for clarity, refine writing standards in AGENTS.md --- .claude/README.md | 2 +- .claude/claude.json | 1 - .claude/instructions.md | 15 +--- AGENTS.md | 151 ++++++---------------------------------- 4 files changed, 23 insertions(+), 146 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index 0953e5590c..aa731834e5 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -95,8 +95,8 @@ Before submitting: npm run lint:md # Check markdown npm run lint:code # Check code vale "path/to/file.md" --minAlertLevel=error # Check prose style +npm run openapi:lint # Validate OpenAPI specs npm start # Preview changes -npm test # Validate API specs ``` ## Best practices diff --git a/.claude/claude.json b/.claude/claude.json index bbf51b38cc..bb46efb7ee 100644 --- a/.claude/claude.json +++ b/.claude/claude.json @@ -1,7 +1,6 @@ { "instructions": "instructions.md", "context": [ - "../AGENTS.md", "../CONTRIBUTING.md" ] } diff --git a/.claude/instructions.md b/.claude/instructions.md index b72582b64f..b58f01dabc 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -1,19 +1,6 @@ # Claude Code instructions for Apify documentation -Read `AGENTS.md` first - it is the single source of truth for project architecture, commands, writing style, and terminology. - -## Claude Code specifics - -Detailed documentation standards are auto-loaded from `.claude/rules/`: - -- `writing-style.md` - Prose voice and tone -- `content-standards.md` - Formatting and structure -- `terminology.md` - Product names and capitalization -- `grammar-rules.md` - Grammar mechanics, punctuation, numbers, brand spelling -- `file-organization.md` - File naming and directory structure -- `quality-standards.md` - Complete quality checklist - -These rules expand on the standards in `AGENTS.md` with detailed examples and tables. +`CLAUDE.md` (symlink to `AGENTS.md`) covers project architecture, commands, and common pitfalls. Documentation standards are auto-loaded from `.claude/rules/` - those are the canonical source for all writing, formatting, and terminology rules. ## Available skills diff --git a/AGENTS.md b/AGENTS.md index 360e23ce4c..af8d8c5350 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,136 +98,27 @@ Use `npm run start:dev` + nginx to serve all repos together locally. See `CONTRI --- -## Writing style +## Writing and style standards -### Language and tone +Detailed documentation standards live in `.claude/rules/`: -- **US English** spelling (analyze, color, not analyse, colour) -- **Active voice** and **imperative tone** ("Install the package", not "You should install") -- **Simple English** - no sentence over 30 words, get to the point -- **Inclusive language** - avoid gendered terms, don't use directional language (left/right) for UI -- No first person ("I recommend") - use "you" for the reader -- No sales language ("ultimate", "cutting-edge", "supercharge") - -### Headings - -- **Sentence case only** - capitalize first word and proper nouns only -- **No gerunds** (-ing forms) - use noun phrases or imperatives -- **Capitalize after colons** when introducing a complete clause -- **Proper hierarchy** - H1 (from frontmatter) → H2 → H3 → H4, never skip levels - -Examples: - -| Avoid | Prefer | +| File | Covers | |---|---| -| Store And Manage Data | Store and manage data | -| Getting Started With Actors | Get started with Actors | -| Step 1: install the dependencies | Step 1: Install the dependencies | - -### Text formatting - -- **Bold** for UI elements only (buttons, menus, fields) and critical warnings -- *Italics* for emphasis and introducing new terms -- `code` for file names, commands, config keys, variables, and code values -- Never use bold for list introductions or general emphasis - -### Admonitions - -All admonitions must have titles (2-3 scannable words). Types: `note`, `tip`, `info`, `caution`, `danger`. - -```markdown -:::note Actor versions -Actors can have multiple versions. Pin to a specific version for production use. -::: -``` - -### Lists - -- Numbered lists (`1.` for all items) for sequential steps -- Bullet points for non-sequential items -- All items must follow the same grammatical pattern (parallel structure) -- Use Oxford commas - -### Links - -- Descriptive, action-oriented link text (never "click here" or "here") -- Internal links use relative paths, never full URLs -- Link external tools to official sites on first mention -- Link Actor names on first mention - -### Em dashes - -Don't use em dashes (—). Use hyphen with spaces ( - ) instead. - -## Content formatting - -### Front matter - -Every `.md`/`.mdx` file requires: - -```yaml ---- -title: Sentence case title -description: 140-160 character description for SEO -sidebar_position: 1.0 -slug: /path/to/page ---- -``` - -### Code examples - -- Complete and runnable -- Syntax highlighting specified for all code blocks -- Code tabs for multi-language examples (JavaScript + Python) -- Version matching between Dockerfile tags and package.json - -### Images - -- Meaningful alt text on all images -- Light theme for screenshots -- Red indicators to highlight UI elements -- Store in `images/` subdirectory next to the markdown file -- PNG for screenshots, SVG for logos - -## Terminology - -### Product names (always capitalize) - -Apify Actor, Apify Proxy, Apify Console, Apify Store, Apify SDK, Apify CLI, Apify API - -### Platform terms (lowercase with "the") - -the Apify platform, the Apify team, the Apify ecosystem - -### Feature terms (always lowercase) - -task, schedule, run, build, dataset, key-value store, request queue, web scraping - -### Generic technical terms (lowercase) - -AI agent, MCP server, API endpoint, web scraper, proxy server - -### Actor references - -First mention: full name with link (`[Website Content Crawler](https://apify.com/apify/website-content-crawler)`). Subsequent mentions: just the name. - -## File organization - -- **Kebab-case** for file names: `web-scraping-basics.md` -- Match slug to file path -- Group related files in logical directories - -## Review checklist - -When creating or reviewing documentation, verify: - -- [ ] Sentence case headings, no gerunds, proper hierarchy -- [ ] Front matter complete (title, description 140-160 chars, sidebar_position, slug) -- [ ] Bold used only for UI elements -- [ ] All admonitions have titles -- [ ] Code examples are complete with syntax highlighting -- [ ] Links use descriptive text, internal links use relative paths -- [ ] Images have alt text, use light theme -- [ ] Terminology matches rules above -- [ ] US English, active voice, no sales language -- [ ] `npm run lint` passes +| `writing-style.md` | US English, active voice, imperative tone, no sales language | +| `content-standards.md` | Front matter, headings, formatting, admonitions, code examples, links, images | +| `terminology.md` | Product names, article usage, feature terms, Actor references | +| `grammar-rules.md` | Hyphenation, contractions, e.g./i.e., numbers, list punctuation, brand spelling | +| `file-organization.md` | Kebab-case naming, directory structure | +| `quality-standards.md` | Complete pre-submission checklist | + +Read these files for the full rules. The most critical rules at a glance: + +- **US English**, active voice, imperative tone, no sales language +- **Sentence case headings** - no title case, no gerunds (-ing forms) +- **Bold for UI elements only** - not for structure or emphasis +- **All admonitions must have titles** +- **No em dashes** - use hyphen with spaces ( - ) instead +- **Terminology** - capitalize product names (Apify Actor, Apify Console), lowercase features (dataset, schedule, run) +- **Numbered lists** use `1.` for all items, with parallel structure +- **Descriptive link text** - no "click here" +- Run `npm run lint` before submitting From 31171aad5dd9cfd7b6f79b8c40d58e42b10605da Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 4 Mar 2026 16:20:19 +0100 Subject: [PATCH 5/6] docs: update content standards and writing style guidelines for clarity and consistency --- .claude/rules/content-standards.md | 181 +--------------------------- .claude/rules/writing-style.md | 185 ++++++++++++++++++++++++++++- AGENTS.md | 4 +- 3 files changed, 187 insertions(+), 183 deletions(-) diff --git a/.claude/rules/content-standards.md b/.claude/rules/content-standards.md index 011bcc5431..01e8c04e74 100644 --- a/.claude/rules/content-standards.md +++ b/.claude/rules/content-standards.md @@ -1,6 +1,6 @@ # Content Standards -Canonical formatting standards for all Apify documentation. These rules ensure consistency across platform docs, academy tutorials, and API references. +Markdown and Docusaurus formatting standards for Apify documentation. For general writing style rules (headings, text formatting, links, numbers), see `writing-style.md`. ## Front matter requirements @@ -50,46 +50,7 @@ slug: /academy/tutorials/web-scraper --- ``` -## Headings - -### Casing - -**Sentence case only.** Capitalize only the first word and proper nouns. - -#### Common mistakes - -| Avoid (Title Case) | Prefer (Sentence case) | Rule | -|-------------------|------------------------|------| -| Store And Manage Data | Store and manage data | Lowercase articles, conjunctions, prepositions | -| Getting Started With Actors | Get started with Actors | "Actors" stays capitalized (Apify product name) | -| Use The Apify SDK | Use the Apify SDK | "SDK" stays capitalized (acronym) | -| Advanced Web Scraping Techniques | Advanced web scraping techniques | Lowercase generic terms | -| Configure GitHub Actions | Configure GitHub Actions | Preserve proper noun capitalization | -| Connect To Google Sheets | Connect to Google Sheets | Lowercase prepositions ("to") | -| Set Up Your Environment | Set up your environment | Lowercase articles ("your") | -| API Reference Documentation | API reference documentation | Keep acronyms capitalized, rest lowercase | -| Working With Docker Containers | Work with Docker containers | "Docker" stays capitalized (product name) | -| Extend The Base Image | Extend the base image | Lowercase "the" mid-sentence | -| How Do I Start? | How do I start? | Capitalize "I" in questions | -| Understanding Request Queues | Understand request queues | Lowercase feature names | -| Enable Standby Mode | Enable standby mode | Lowercase mode names | -| Access The Apify Console | Access Apify Console | "Apify Console" stays capitalized (product), no "the" | -| Run Your First Actor | Run your first Actor | "Actor" capitalized, "your" lowercase | -| Manage Node Modules | Manage node modules | Lowercase generic terms | -| Step 1: install the dependencies | Step 1: Install the dependencies | Capitalize after colon (starts new clause) | -| Option 2: use the alternative approach | Option 2: Use the alternative approach | Capitalize after colon (starts new clause) | - -### Form - -**No gerunds (-ing forms).** Use noun phrases or imperatives. - -| Avoid | Prefer | -|-------|--------| -| Finding available tags | Available tags | -| Getting started with Actors | Get started with Actors | -| Understanding the API | API overview | - -### Hierarchy +## Heading hierarchy Follow proper heading hierarchy: H2 → H3 → H4. Never skip levels. (H1 is the page title, set in front matter) @@ -101,48 +62,6 @@ Follow proper heading hierarchy: H2 → H3 → H4. Never skip levels. (H1 is the #### Detail (H4 - use sparingly) ``` -## Text formatting - -### Bold - -**Do use bold for:** -- UI elements (buttons, menus, fields, tabs) -- Critical warnings or key terms that must stand out - -**Don't use bold for:** -- List introductions or section labels -- Code block introductions -- General emphasis (use italics instead) -- Structural labels when context is clear - -| Avoid | Prefer | -|-------|--------| -| **Examples:** | Examples: | -| **In your Dockerfile**, use... | In your `Dockerfile`, use... | - -### Italics - -Use italics for emphasis and introducing new terms: - -| Use case | Example | -|----------|---------| -| New term introduction | An *Actor* is a serverless program... | -| Emphasis | This step is *required* for the Actor to work | - -### Code formatting - -Use backticks for inline code: - -- File names: `Dockerfile`, `package.json`, `.actor/actor.json` -- Commands: `npm install`, `docker build` -- Config keys: `actorSpecification`, `dockerfile` -- Variable names: `API_TOKEN`, `userId` -- Code values: `true`, `null`, `"string"` - -### Em dashes - -Don't use em dashes (—). Use hyphen with spaces ( - ) instead. - ## Admonitions Use Docusaurus admonitions for important information. **All admonitions MUST have titles.** @@ -264,27 +183,6 @@ FROM apify/actor-node-playwright:22 ## Links -### Descriptive link text - -Use action-oriented, descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. - -| Avoid | Prefer | -|-------|--------| -| `[Click here](url)` to learn more | `[Learn about Actor pricing](url)` | -| Read more about it `[here](url)` | Read the `[Actor development guide](url)` | -| See the `[documentation](url)` | `[Read the API documentation](url)` | - -### Action verbs for links - -Match the verb to the content type: - -| Content type | Verbs | -|--------------|-------| -| Documentation | Read, View, Check, See | -| Tutorials | Learn, Build, Follow | -| Reference | Access, Browse, Explore | -| Examples | View, Try, Clone | - ### Internal vs external links **Internal links** (within apify-docs): @@ -295,32 +193,6 @@ Match the verb to the content type: - Use full URLs: `[Playwright](https://playwright.dev)` - Make tool mentions navigable -### Actor references - -First mention: Actor name with link, capitalized. - -```markdown -[Website Content Crawler](https://apify.com/apify/website-content-crawler) -can crawl websites and extract text content. -``` - -Subsequent mentions: Just the name, no link needed. - -### Tool mentions - -When mentioning tools, languages, or external resources, link to their official site: - -| Avoid | Prefer | -|-------|--------| -| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | - -### Trim link filler - -| Avoid | Prefer | -|-------|--------| -| visit the Docker Hub tags page | visit Docker Hub | -| check out the official docs | check the documentation | - ## Images ### Alt text @@ -363,56 +235,15 @@ platform/ │ └── run-button.png ``` -## Numbers and formatting - -### Thousands and decimals - -- Thousands: comma separator ($1,000) -- Decimals: period ($9.8) - -### Money - -- Symbol before amount: $49 (not 49$) -- Include currency: $49 USD for international context +## Lists -### Dates - -- Format: Month Day, Year -- Example: August 5, 2024 -- Never: 5.8.2024 or 2024-08-05 in prose (ISO format OK in code) -- No ordinal suffixes: "August 5" not "August 5th" -- No abbreviated months: "January" not "Jan" - -### Time - -- Format: 12-hour with space before AM/PM -- Example: 5 PM, 11:30 AM -- Uppercase: PM (not pm or p.m.) -- Never use periods: "5 PM" not "5 p.m." - -## Parallel structure - -All items in a list must follow the same grammatical pattern: - -**Avoid - mixed patterns:** -```markdown -1. Reproducibility - your builds behave the same -1. Predictability - you know which version -1. Easier to track down issues -``` - -**Prefer - consistent pattern:** -```markdown -1. Reproducibility - Your builds behave the same way -1. Predictability - You know exactly which version you're running -1. Debugging - Version-specific issues are easier to track down -``` - -## List types +### List types - **Numbered lists**: Sequential steps where order matters - **Bullet points**: Non-sequential items, features, options +### Numbered list convention + In numbered lists, use `1.` for all items (not sequential numbers): ```markdown diff --git a/.claude/rules/writing-style.md b/.claude/rules/writing-style.md index 0dc07e5928..1e4b820a86 100644 --- a/.claude/rules/writing-style.md +++ b/.claude/rules/writing-style.md @@ -93,6 +93,181 @@ Acceptable uses of "our" - direct team actions or invitations: - "We're excited to announce..." (team action) - "Join our webinar" (direct invitation) +## Headings + +### Casing + +**Sentence case only.** Capitalize only the first word and proper nouns. + +#### Common mistakes + +| Avoid (Title Case) | Prefer (Sentence case) | Rule | +|-------------------|------------------------|------| +| Store And Manage Data | Store and manage data | Lowercase articles, conjunctions, prepositions | +| Getting Started With Actors | Get started with Actors | "Actors" stays capitalized (Apify product name) | +| Use The Apify SDK | Use the Apify SDK | "SDK" stays capitalized (acronym) | +| Advanced Web Scraping Techniques | Advanced web scraping techniques | Lowercase generic terms | +| Configure GitHub Actions | Configure GitHub Actions | Preserve proper noun capitalization | +| Connect To Google Sheets | Connect to Google Sheets | Lowercase prepositions ("to") | +| Set Up Your Environment | Set up your environment | Lowercase articles ("your") | +| API Reference Documentation | API reference documentation | Keep acronyms capitalized, rest lowercase | +| Working With Docker Containers | Work with Docker containers | "Docker" stays capitalized (product name) | +| Extend The Base Image | Extend the base image | Lowercase "the" mid-sentence | +| How Do I Start? | How do I start? | Capitalize "I" in questions | +| Understanding Request Queues | Understand request queues | Lowercase feature names | +| Enable Standby Mode | Enable standby mode | Lowercase mode names | +| Access The Apify Console | Access Apify Console | "Apify Console" stays capitalized (product), no "the" | +| Run Your First Actor | Run your first Actor | "Actor" capitalized, "your" lowercase | +| Manage Node Modules | Manage node modules | Lowercase generic terms | +| Step 1: install the dependencies | Step 1: Install the dependencies | Capitalize after colon (starts new clause) | +| Option 2: use the alternative approach | Option 2: Use the alternative approach | Capitalize after colon (starts new clause) | + +### Form + +**No gerunds (-ing forms).** Use noun phrases or imperatives. + +| Avoid | Prefer | +|-------|--------| +| Finding available tags | Available tags | +| Getting started with Actors | Get started with Actors | +| Understanding the API | API overview | + +## Text formatting + +### Bold + +**Do use bold for:** +- UI elements (buttons, menus, fields, tabs) +- Critical warnings or key terms that must stand out + +**Don't use bold for:** +- List introductions or section labels +- Code block introductions +- General emphasis (use italics instead) +- Structural labels when context is clear + +| Avoid | Prefer | +|-------|--------| +| **Examples:** | Examples: | +| **In your Dockerfile**, use... | In your `Dockerfile`, use... | + +### Italics + +Use italics for emphasis and introducing new terms: + +| Use case | Example | +|----------|---------| +| New term introduction | An *Actor* is a serverless program... | +| Emphasis | This step is *required* for the Actor to work | + +### Code formatting + +Use backticks for inline code: + +- File names: `Dockerfile`, `package.json`, `.actor/actor.json` +- Commands: `npm install`, `docker build` +- Config keys: `actorSpecification`, `dockerfile` +- Variable names: `API_TOKEN`, `userId` +- Code values: `true`, `null`, `"string"` + +### Em dashes + +Don't use em dashes (—). Use hyphen with spaces ( - ) instead. + +## Links + +### Descriptive link text + +Use action-oriented, descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. + +| Avoid | Prefer | +|-------|--------| +| `[Click here](url)` to learn more | `[Learn about Actor pricing](url)` | +| Read more about it `[here](url)` | Read the `[Actor development guide](url)` | +| See the `[documentation](url)` | `[Read the API documentation](url)` | + +### Action verbs for links + +Match the verb to the content type: + +| Content type | Verbs | +|--------------|-------| +| Documentation | Read, View, Check, See | +| Tutorials | Learn, Build, Follow | +| Reference | Access, Browse, Explore | +| Examples | View, Try, Clone | + +### Actor references + +First mention: Actor name with link, capitalized. + +```markdown +[Website Content Crawler](https://apify.com/apify/website-content-crawler) +can crawl websites and extract text content. +``` + +Subsequent mentions: Just the name, no link needed. + +### Tool mentions + +When mentioning tools, languages, or external resources, link to their official site: + +| Avoid | Prefer | +|-------|--------| +| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | + +### Trim link filler + +| Avoid | Prefer | +|-------|--------| +| visit the Docker Hub tags page | visit Docker Hub | +| check out the official docs | check the documentation | + +## Numbers and formatting + +### Thousands and decimals + +- Thousands: comma separator ($1,000) +- Decimals: period ($9.8) + +### Money + +- Symbol before amount: $49 (not 49$) +- Include currency: $49 USD for international context + +### Dates + +- Format: Month Day, Year +- Example: August 5, 2024 +- Never: 5.8.2024 or 2024-08-05 in prose (ISO format OK in code) +- No ordinal suffixes: "August 5" not "August 5th" +- No abbreviated months: "January" not "Jan" + +### Time + +- Format: 12-hour with space before AM/PM +- Example: 5 PM, 11:30 AM +- Uppercase: PM (not pm or p.m.) +- Never use periods: "5 PM" not "5 p.m." + +## Parallel structure + +All items in a list must follow the same grammatical pattern: + +**Avoid - mixed patterns:** +```markdown +1. Reproducibility - your builds behave the same +1. Predictability - you know which version +1. Easier to track down issues +``` + +**Prefer - consistent pattern:** +```markdown +1. Reproducibility - Your builds behave the same way +1. Predictability - You know exactly which version you're running +1. Debugging - Version-specific issues are easier to track down +``` + ## Grammar ### Articles in definitions @@ -111,10 +286,6 @@ Always use the serial comma: | ---------------------------- | -------------------------------- | | pencil, eraser and notebook | pencil, eraser, and notebook | -## Formatting, links, and code - -See `content-standards.md` for all formatting rules (headings, bold, code, admonitions, lists, links, images, numbers). See `grammar-rules.md` for grammar mechanics (hyphenation, contractions, e.g./i.e., list punctuation). - ## Common Mistakes Patterns to avoid: @@ -132,8 +303,10 @@ Patterns to avoid: ## Reference -This guide covers writing patterns. For structural guidelines (file naming, screenshots, tutorial structure, SEO), see: +This guide covers writing patterns. For additional rules, see: +- `content-standards.md` - Markdown and Docusaurus formatting (front matter, admonitions, code blocks, images, lists) +- `grammar-rules.md` - Detailed grammar mechanics (hyphenation, contractions, e.g./i.e., list punctuation) +- `terminology.md` - Apify product names, capitalization, and word choice - [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution workflow and repository standards -- [AGENTS.md](../../AGENTS.md) - Comprehensive documentation guidelines for AI assistants - Full Apify style guide: https://www.notion.so/apify/Apify-style-guide-1b9f39950a2280d49e5be69ce2961a79 diff --git a/AGENTS.md b/AGENTS.md index af8d8c5350..2d821787a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,8 +104,8 @@ Detailed documentation standards live in `.claude/rules/`: | File | Covers | |---|---| -| `writing-style.md` | US English, active voice, imperative tone, no sales language | -| `content-standards.md` | Front matter, headings, formatting, admonitions, code examples, links, images | +| `writing-style.md` | Voice, tone, headings, text formatting, links, numbers, parallel structure | +| `content-standards.md` | Front matter, heading hierarchy, admonitions, code blocks, images, lists | | `terminology.md` | Product names, article usage, feature terms, Actor references | | `grammar-rules.md` | Hyphenation, contractions, e.g./i.e., numbers, list punctuation, brand spelling | | `file-organization.md` | Kebab-case naming, directory structure | From e8c11cb42763231a85c88d93d10a2b43c7c6cad0 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 4 Mar 2026 16:28:52 +0100 Subject: [PATCH 6/6] docs: enhance writing style guidelines for clarity and consistency --- AGENTS.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 130 insertions(+), 21 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2d821787a5..360e23ce4c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,27 +98,136 @@ Use `npm run start:dev` + nginx to serve all repos together locally. See `CONTRI --- -## Writing and style standards +## Writing style -Detailed documentation standards live in `.claude/rules/`: +### Language and tone -| File | Covers | +- **US English** spelling (analyze, color, not analyse, colour) +- **Active voice** and **imperative tone** ("Install the package", not "You should install") +- **Simple English** - no sentence over 30 words, get to the point +- **Inclusive language** - avoid gendered terms, don't use directional language (left/right) for UI +- No first person ("I recommend") - use "you" for the reader +- No sales language ("ultimate", "cutting-edge", "supercharge") + +### Headings + +- **Sentence case only** - capitalize first word and proper nouns only +- **No gerunds** (-ing forms) - use noun phrases or imperatives +- **Capitalize after colons** when introducing a complete clause +- **Proper hierarchy** - H1 (from frontmatter) → H2 → H3 → H4, never skip levels + +Examples: + +| Avoid | Prefer | |---|---| -| `writing-style.md` | Voice, tone, headings, text formatting, links, numbers, parallel structure | -| `content-standards.md` | Front matter, heading hierarchy, admonitions, code blocks, images, lists | -| `terminology.md` | Product names, article usage, feature terms, Actor references | -| `grammar-rules.md` | Hyphenation, contractions, e.g./i.e., numbers, list punctuation, brand spelling | -| `file-organization.md` | Kebab-case naming, directory structure | -| `quality-standards.md` | Complete pre-submission checklist | - -Read these files for the full rules. The most critical rules at a glance: - -- **US English**, active voice, imperative tone, no sales language -- **Sentence case headings** - no title case, no gerunds (-ing forms) -- **Bold for UI elements only** - not for structure or emphasis -- **All admonitions must have titles** -- **No em dashes** - use hyphen with spaces ( - ) instead -- **Terminology** - capitalize product names (Apify Actor, Apify Console), lowercase features (dataset, schedule, run) -- **Numbered lists** use `1.` for all items, with parallel structure -- **Descriptive link text** - no "click here" -- Run `npm run lint` before submitting +| Store And Manage Data | Store and manage data | +| Getting Started With Actors | Get started with Actors | +| Step 1: install the dependencies | Step 1: Install the dependencies | + +### Text formatting + +- **Bold** for UI elements only (buttons, menus, fields) and critical warnings +- *Italics* for emphasis and introducing new terms +- `code` for file names, commands, config keys, variables, and code values +- Never use bold for list introductions or general emphasis + +### Admonitions + +All admonitions must have titles (2-3 scannable words). Types: `note`, `tip`, `info`, `caution`, `danger`. + +```markdown +:::note Actor versions +Actors can have multiple versions. Pin to a specific version for production use. +::: +``` + +### Lists + +- Numbered lists (`1.` for all items) for sequential steps +- Bullet points for non-sequential items +- All items must follow the same grammatical pattern (parallel structure) +- Use Oxford commas + +### Links + +- Descriptive, action-oriented link text (never "click here" or "here") +- Internal links use relative paths, never full URLs +- Link external tools to official sites on first mention +- Link Actor names on first mention + +### Em dashes + +Don't use em dashes (—). Use hyphen with spaces ( - ) instead. + +## Content formatting + +### Front matter + +Every `.md`/`.mdx` file requires: + +```yaml +--- +title: Sentence case title +description: 140-160 character description for SEO +sidebar_position: 1.0 +slug: /path/to/page +--- +``` + +### Code examples + +- Complete and runnable +- Syntax highlighting specified for all code blocks +- Code tabs for multi-language examples (JavaScript + Python) +- Version matching between Dockerfile tags and package.json + +### Images + +- Meaningful alt text on all images +- Light theme for screenshots +- Red indicators to highlight UI elements +- Store in `images/` subdirectory next to the markdown file +- PNG for screenshots, SVG for logos + +## Terminology + +### Product names (always capitalize) + +Apify Actor, Apify Proxy, Apify Console, Apify Store, Apify SDK, Apify CLI, Apify API + +### Platform terms (lowercase with "the") + +the Apify platform, the Apify team, the Apify ecosystem + +### Feature terms (always lowercase) + +task, schedule, run, build, dataset, key-value store, request queue, web scraping + +### Generic technical terms (lowercase) + +AI agent, MCP server, API endpoint, web scraper, proxy server + +### Actor references + +First mention: full name with link (`[Website Content Crawler](https://apify.com/apify/website-content-crawler)`). Subsequent mentions: just the name. + +## File organization + +- **Kebab-case** for file names: `web-scraping-basics.md` +- Match slug to file path +- Group related files in logical directories + +## Review checklist + +When creating or reviewing documentation, verify: + +- [ ] Sentence case headings, no gerunds, proper hierarchy +- [ ] Front matter complete (title, description 140-160 chars, sidebar_position, slug) +- [ ] Bold used only for UI elements +- [ ] All admonitions have titles +- [ ] Code examples are complete with syntax highlighting +- [ ] Links use descriptive text, internal links use relative paths +- [ ] Images have alt text, use light theme +- [ ] Terminology matches rules above +- [ ] US English, active voice, no sales language +- [ ] `npm run lint` passes