docs: Consolidate style guide into standards/ directory

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+<!--
+Keep the description to one or two sentences: what changed and why.
+Skip boilerplate headings (## Summary, ## Changes) and bullet lists that restate the diff - the diff is the record of what changed, the description explains the why.
+Use a Conventional Commits title (docs:, fix:, feat:, ...) - CI enforces it.
+-->

AGENTS.md

@@ -132,7 +132,7 @@ Use `pnpm start:dev` + nginx to serve all repos together locally. See `CONTRIBUT
 - Auto-deploy on merge to `master`
 - Preview builds on pull requests
 - PR titles must use [Conventional Commits](https://www.conventionalcommits.org/) format (`docs:`, `fix:`, `feat:`, etc.) - enforced by CI
-- Keep PR descriptions short - one or two sentences covering what changed and why. Skip boilerplate headings (`## Summary`, `## Changes`, `## Details`), bullet lists that restate the diff, and filler text. The diff is the record of what changed; the description explains the why.
+- Keep PR descriptions to one or two sentences - what changed and why. No boilerplate headings, no bullet lists restating the diff. See the pull request process in `CONTRIBUTING.md`
 
 ## Common pitfalls
 
@@ -152,7 +152,7 @@ Use `pnpm start:dev` + nginx to serve all repos together locally. See `CONTRIBUT
 
 ## Standards
 
-Detailed writing and formatting standards are in `standards/`:
+Detailed writing and formatting standards are in `standards/`. This is the single source of truth for docs rules - `CONTRIBUTING.md` and `.cursor/rules/` point here instead of restating them, so a rule change lands in `standards/` only:
 
 - `standards/writing-style.md` - Prose voice, tone, headings, links, numbers
 - `standards/content-standards.md` - Front matter, admonitions, code blocks, images
@@ -167,7 +167,8 @@ Key rules at a glance:
 - Sentence case headings, no gerunds
 - Bold for UI elements only; `code` for filenames, commands, variables
 - All admonitions require titles
-- 140-160 character descriptions in front matter
+- 140-160 character descriptions in front matter, action-oriented, without the word "documentation"
+- Screenshots only when they add something the prose doesn't; light theme, `#F86606` highlights, no arrows
 - See `standards/terminology.md` for Apify product name capitalization
 - Don't use em dashes (—) - use hyphen with spaces ( - ) instead
 
@@ -190,7 +191,7 @@ When creating or reviewing documentation, verify:
 - [ ] 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
+- [ ] Images have alt text, use light theme and `#F86606` highlights
 - [ ] Terminology matches rules above
 - [ ] US English, active voice, no sales language
 - [ ] `pnpm lint` passes

CONTRIBUTING.md

@@ -4,7 +4,7 @@
 
 1. Review this guide completely
 2. Setup you development environment
-3. Familiarize yourself with our documentation style guide
+3. Familiarize yourself with the [documentation style guide](standards/)
 
 ## Development setup
 
@@ -77,65 +77,16 @@ You should be able to open https://docs.apify.loc in your browser and run all th
 
 ## Documentation style guide
 
-### Language guidelines
+The style guide lives in [`standards/`](standards/), which is the single source of truth for both people and AI assistants. Rules aren't repeated here, so there's nothing to keep in sync:
 
-- Use US English
-- Write in inclusive language
-- Avoid directional language (like "left" or "right" or instead of "see" use "check out")
-- Use active voice whenever possible
+- [`standards/writing-style.md`](standards/writing-style.md) - US English, active and inclusive voice, headings, text emphasis, links, numbers
+- [`standards/content-standards.md`](standards/content-standards.md) - Front matter, admonitions, code blocks and code tabs, images and screenshots
+- [`standards/terminology.md`](standards/terminology.md) - Apify product names, capitalization, article usage
+- [`standards/grammar-rules.md`](standards/grammar-rules.md) - Hyphenation, punctuation, numbers, brand spelling
+- [`standards/file-organization.md`](standards/file-organization.md) - File naming (kebab-case) and directory structure
+- [`standards/quality-standards.md`](standards/quality-standards.md) - Checklist to run through before opening a pull request
 
-### Formatting conventions
-
-1. Text emphasis:
-
-    - use **Bold** for UI elements
-    - use _Italics_ for emphasis
-    - use `code` for inline code, by using back-ticks (\`\`\)
-    - use code blocks with language specification
-    - use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) whenever you want to include examples of implementation in more than one language
-
-2. Documentation elements:
-
-    - Use [admonitions](https://docusaurus.io/docs/2.x/markdown-features/admonitions) to emphasize crucial information, available admonitions are:
-      - note
-      - tip
-      - info
-      - caution
-      - danger
-    - Use code tabs for multiple languages
-    - Include proper metadata in front matter
-    - Use concise, meaningful headings:
-      - Use sentence case.
-      - Avoid question-like titles ("How to...", "What is...").
-      - Don't use gerunds.
-
-    Example of proper usage and formatting:
-
-    ```text
-    :::note Your Title Here
-
-    Your important message here.
-
-    :::
-    ```
-
-3. Screenshots:
-
-    - Keep screenshots to a minimum. If an image shows what your prose already describes, it's probably not needed.
-    - Always include meaningful alt texts. Remember that it might be the only way for some users to understand the content.
-    - Use light theme when taking screenshots.
-    - To highlight UI elements, use `#F86606` color for indicators. Don't use arrows.
-
-### Front matter metadata best practices
-
-- Keep descriptions between 140 and 160 characters
-- Use action-oriented phrasing
-- Avoid repetitive keywords
-- Avoid the word "documentation" in descriptions
-
-### File naming conventions
-
-For file names, use lowercase letters and hyphens (kebab-case). For example `web-scraping-basics.mdx`
+[`AGENTS.md`](AGENTS.md) condenses these into the rules an AI assistant loads first. Change a rule in `standards/`, not in `AGENTS.md` or here.
 
 ## AI assistant rules structure
 
@@ -344,9 +295,9 @@ Add languages by adding new folders at the appropriate path level.
 
 ## Pull request process
 
-1. Follow [Conventional Commits](https://www.conventionalcommits.org/)
-2. Pass all CI checks
-3. Include comprehensive documentation updates
+1. Title follows [Conventional Commits](https://www.conventionalcommits.org/) - CI enforces it
+2. Description is one or two sentences: what changed and why. Skip boilerplate headings (`## Summary`, `## Changes`) and bullet lists that restate the diff - the diff is the record of what changed, the description explains the why. [`.github/pull_request_template.md`](.github/pull_request_template.md) repeats this as a reminder in the PR form
+3. All CI checks pass
 
 ## Deployment
 

README.md

@@ -26,7 +26,7 @@ Documentation ecosystem consists of:
 **Before contributing, read these essential resources:**
 
 - [Contributing guidelines](CONTRIBUTING.md) - Complete setup and contribution process
-- [Documentation style guide](CONTRIBUTING.md#documentation-style-guide) - Writing standards and formatting
+- [Documentation style guide](standards/) - Writing standards and formatting, the source of truth for people and AI assistants
 - [AI Assistant Rules Structure](CONTRIBUTING.md#ai-assistant-rules-structure) - AI tool configuration
 
 ### Prerequisites

standards/content-standards.md

@@ -18,7 +18,7 @@ slug: /path/to/page
 ### Required fields
 
 - **title**: Sentence case, present tense (e.g., "Create your first Actor")
-- **description**: 140-160 characters for SEO, clear and actionable
+- **description**: 140-160 characters for SEO, clear and actionable. Use action-oriented phrasing, avoid repeating the same keyword, and don't use the word "documentation"
 - **sidebar_position**: Decimal number for ordering (1.0, 1.1, 2.0, etc.)
 - **slug**: URL path starting with `/` (e.g., `/platform/actors/running`)
 
@@ -189,6 +189,10 @@ All images must include meaningful alt text describing the content:
 ![Apify Console showing the Actor creation dialog](./images/create-actor.webp)
 ```
 
+### When to use a screenshot
+
+Keep screenshots to a minimum. If an image only shows what the prose already describes, leave it out. Screenshots go stale with every UI change, so add one when it carries information the text can't.
+
 ### Theme
 
 Screenshots should use:
@@ -198,10 +202,11 @@ Screenshots should use:
 
 ### Visual indicators
 
-Use red boxes or arrows to highlight important UI elements:
-- **Red border**: Highlight clickable elements (buttons, fields)
-- **Red arrow**: Point to specific areas
-- **Red circle**: Highlight small elements
+Highlight UI elements with the `#F86606` (Apify orange) color:
+- **Border**: Highlight clickable elements (buttons, fields)
+- **Circle**: Highlight small elements
+
+Don't use arrows.
 
 ### Image format
 

standards/quality-standards.md

@@ -80,7 +80,8 @@ Before submitting documentation, verify:
 
 - [ ] All images include meaningful alt text
 - [ ] Screenshots use light theme
-- [ ] Red indicators used to highlight UI elements
+- [ ] UI highlights use `#F86606`, no arrows
+- [ ] Screenshots earn their place (no image that only repeats the prose)
 - [ ] Images stored in `images/` subdirectory
 - [ ] Image format is appropriate (WebP for screenshots, SVG for logos, icons, and product images)
 

standards/writing-style.md

@@ -75,6 +75,7 @@ Use active voice. Avoid gendered terms. Don't use directional language ("left/ri
 | The Actor is started by the user  | The user starts the Actor        |
 | He can configure his settings     | You can configure your settings  |
 | Click the button on the left      | Click the **Settings** button    |
+| See the storage guide             | Check out the storage guide      |
 
 ### Avoid "our"
 
@@ -112,7 +113,6 @@ Acceptable uses of "our" - direct team actions or invitations:
 | 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" |
@@ -127,6 +127,13 @@ Acceptable uses of "our" - direct team actions or invitations:
 
 > Enforced by Vale (`Apify.HeadingGerund`). Run `vale "<file>"` to check.
 
+**No question-like headings.** Answer the question instead of asking it.
+
+| Avoid                        | Prefer                  |
+| ---------------------------- | ----------------------- |
+| How to run an Actor          | Run an Actor            |
+| What is a request queue?     | Request queues          |
+
 ## Text formatting
 
 ### Bold