diff --git a/.claude/README.md b/.claude/README.md index 2744cd0c14..aa731834e5 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: @@ -92,8 +94,9 @@ 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 run openapi:lint # Validate OpenAPI specs npm start # Preview changes -npm test # Validate API specs ``` ## Best practices @@ -101,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/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 5d8abab214..b58f01dabc 100644 --- a/.claude/instructions.md +++ b/.claude/instructions.md @@ -1,18 +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` - 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 - -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/.claude/rules/content-standards.md b/.claude/rules/content-standards.md index fc22493aa7..01e8c04e74 100644 --- a/.claude/rules/content-standards.md +++ b/.claude/rules/content-standards.md @@ -1,12 +1,6 @@ ---- -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. +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 @@ -56,97 +50,18 @@ 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 the Apify Console | "Apify Console" stays capitalized (product) | -| 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) | +## Heading hierarchy -### 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 - -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) #### 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"` - ## Admonitions Use Docusaurus admonitions for important information. **All admonitions MUST have titles.** @@ -268,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): @@ -299,17 +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. - ## Images ### Alt text @@ -352,53 +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 - -### Dates - -- Format: Month Day, Year -- Example: August 5, 2024 -- Never: 5.8.2024 or 2024-08-05 in prose (ISO format OK in code) - -### Time - -- Format: 12-hour with space before AM/PM -- Example: 5 PM, 11:30 AM -- Uppercase: PM (not pm or 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 -``` +## Lists -## 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/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 new file mode 100644 index 0000000000..d3d36f79ca --- /dev/null +++ b/.claude/rules/grammar-rules.md @@ -0,0 +1,169 @@ +# 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 | +| VSCode, VS code | VS Code | +| DockerFile, dockerfile | Dockerfile | diff --git a/.claude/rules/quality-standards.md b/.claude/rules/quality-standards.md index dff1f031dc..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. @@ -62,6 +56,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/rules/terminology.md b/.claude/rules/terminology.md index 484c0c7b61..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. @@ -20,6 +14,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 +99,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 +116,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..1e4b820a86 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. @@ -34,6 +28,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,216 +77,214 @@ 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 "our" -| 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? | +Replace "our" with "the" or "Apify" to keep docs product-focused rather than company-focused. -**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 | +| Avoid | Prefer | +| -------------------- | ------------------------- | +| our team | the Apify team | +| our platform | the Apify platform | +| our API | the Apify API | +| our documentation | the Apify documentation | + +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 | -| 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 | +| Avoid | Prefer | +|-------|--------| +| Finding available tags | Available tags | +| Getting started with Actors | Get started with Actors | +| Understanding the API | API overview | -Rationale: Noun-phrase headings are more scannable and search-friendly (Microsoft style guide). +## Text formatting ### Bold **Do use bold for:** - -- UI elements (buttons, menus, fields): Click the **Actors** button -- Critical warnings or key terms +- UI elements (buttons, menus, fields, tabs) +- Critical warnings or key terms that must stand out **Don't use bold for:** - -- List introductions +- List introductions or section labels - Code block introductions -- Section labels when context is clear +- General emphasis (use italics instead) +- Structural 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. +| 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 | - -### 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 +| Use case | Example | +|----------|---------| +| New term introduction | An *Actor* is a serverless program... | +| Emphasis | This step is *required* for the Actor to work | -All items in a list must follow the same grammatical pattern: +### Code formatting -```markdown -# Avoid - mixed patterns -1. Reproducibility - your builds behave the same -1. Predictability - you know which version -1. Easier to track down issues +Use backticks for inline code: -# 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 -``` +- 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 (—).** LLMs overuse them. Use hyphen with spaces ( - ) instead. +Don't use em dashes (—). Use hyphen with spaces ( - ) instead. -### Admonitions +## Links -Use Docusaurus admonitions for important information: +### Descriptive link text -| Type | Use for | -| ------------ | ------------------------------------------- | -| `:::note` | General callouts | -| `:::tip` | Helpful suggestions | -| `:::info` | Background context | -| `:::caution` | Warnings about gotchas | -| `:::danger` | Critical warnings that could cause issues | +Use action-oriented, descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. -**All admonitions require titles.** Use 2-3 words that are scannable and summarize the content. +| 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)` | -| Avoid | Prefer | -| --------------------------------------- | -------------------------- | -| `:::note Note` | `:::note Actor versions` | -| `:::caution Be careful when deleting` | `:::caution Data loss` | -| `:::tip` (no title) | `:::tip Performance` | +### Action verbs for links -Prefer admonitions over block quotes for highlighted content. +Match the verb to the content type: -## Grammar +| Content type | Verbs | +|--------------|-------| +| Documentation | Read, View, Check, See | +| Tutorials | Learn, Build, Follow | +| Reference | Access, Browse, Explore | +| Examples | View, Try, Clone | -### Articles in definitions +### Actor references -Include "a/an" before nouns in definition lists: +First mention: Actor name with link, capitalized. -| Avoid | Prefer | -| ---------------------------------- | ------------------------------------ | -| `{version}` - Node.js version only | `{version}` - A Node.js version only | +```markdown +[Website Content Crawler](https://apify.com/apify/website-content-crawler) +can crawl websites and extract text content. +``` -### Oxford comma +Subsequent mentions: Just the name, no link needed. -Always use the serial comma: +### Tool mentions -| Avoid | Prefer | -| ---------------------------- | -------------------------------- | -| pencil, eraser and notebook | pencil, eraser, and notebook | +When mentioning tools, languages, or external resources, link to their official site: -### "the" before products +| Avoid | Prefer | +|-------|--------| +| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | -Use "the" before "Apify platform", "Apify SDK", etc. +### Trim link filler -| Avoid | Prefer | -| -------------------- | ------------------------- | -| I use Apify platform | I use the Apify platform | +| Avoid | Prefer | +|-------|--------| +| visit the Docker Hub tags page | visit Docker Hub | +| check out the official docs | check the documentation | -## Terminology +## Numbers and formatting -See `terminology.md` for complete Apify-specific terminology and capitalization rules. +### Thousands and decimals -## Links +- Thousands: comma separator ($1,000) +- Decimals: period ($9.8) -### Action-oriented text +### Money -| Avoid | Prefer | -| --------------------------------- | --------------------------------------- | -| [actor-node-playwright tags](url) | [View actor-node-playwright tags](url) | -| See the [documentation](url) | [Read the documentation](url) | +- Symbol before amount: $49 (not 49$) +- Include currency: $49 USD for international context -### Accessible link text +### Dates -Use descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context. +- 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" -| 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)` | +### Time -### Make tool mentions navigable +- 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." -When mentioning tools, languages, or external resources, link them to help readers explore: +## Parallel structure -| Avoid | Prefer | -| ----------------------------------- | ----------------------------------------------------------- | -| You can use Playwright for this | You can use [Playwright](https://playwright.dev) for this | +All items in a list must follow the same grammatical pattern: -### Trim filler words +**Avoid - mixed patterns:** +```markdown +1. Reproducibility - your builds behave the same +1. Predictability - you know which version +1. Easier to track down issues +``` -| Avoid | Prefer | -| ------------------------------ | --------------------- | -| visit the Docker Hub tags page | visit Docker Hub | -| check out the official docs | check the documentation | +**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 +``` -### Actor references +## Grammar -First mention: Actor name with link, capitalized. +### Articles in definitions -```markdown -[Website Content Crawler](https://apify.com/apify/website-content-crawler) -can crawl websites and extract text content. -``` +Include "a/an" before nouns in definition lists: -## Code Examples +| Avoid | Prefer | +| ---------------------------------- | ------------------------------------ | +| `{version}` - Node.js version only | `{version}` - A Node.js version only | -- 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) +### Oxford comma -## Numbers & Formatting +Always use the serial comma: -- 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) +| Avoid | Prefer | +| ---------------------------- | -------------------------------- | +| pencil, eraser and notebook | pencil, eraser, and notebook | ## Common Mistakes @@ -294,11 +299,14 @@ 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 -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/.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 d5185d444e..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 @@ -13,58 +14,56 @@ 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 +vale "path/to/file.md" --minAlertLevel=error # Vale - Prose and style ``` -### Step 3: Manual review - -Go through the checklist below, noting issues found. - -#### Writing quality - -- [ ] 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` - -#### Front matter - -- [ ] `title` - Sentence case, simple present tense -- [ ] `description` - 140-160 chars, value-focused (not feature list) -- [ ] `slug` - Matches file path -- [ ] `sidebar_position` - Appropriate numbering +## Review checklist -#### Content structure +### Style compliance (delegated) -- [ ] Clear introduction -- [ ] Proper heading hierarchy (H1 → H2 → H3, no skips) -- [ ] Logical topic progression -- [ ] Summary/next steps at end -- [ ] Related content linked +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. -#### Formatting +Check content compliance against: -- [ ] 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) +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 -#### Content-type checks +Each subagent should return a list of violations with line numbers and suggested fixes. -- **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 +### Content review (manual) -### Step 4: Provide feedback +These aspects require judgment and aren't covered by the rules files: -Format your review using the template in `references/review-format.md`. +- [ ] **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 ## Examples @@ -75,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