Skip to content

docs: Fix copy using Dave's LLM style guide#2339

Open
mtrunkat wants to merge 10 commits intomasterfrom
claude/apify-style-guide-EuhBP
Open

docs: Fix copy using Dave's LLM style guide#2339
mtrunkat wants to merge 10 commits intomasterfrom
claude/apify-style-guide-EuhBP

Conversation

@mtrunkat
Copy link
Member

@mtrunkat mtrunkat commented Mar 16, 2026

*TL;DR: I used @davidjohnbarton's Apify LLM styleguide against the whole documentation, and these are the fixes.

Summary

This PR standardizes punctuation and article usage across documentation files for improved consistency and readability.

Key Changes

  • Em dash to hyphen conversion: Replaced em dashes (—) with hyphens (-) in various contexts throughout the documentation, particularly in lists and explanatory phrases
  • Article standardization:
    • Changed "our" to "the" when referring to tools, libraries, and services (e.g., "our universal scrapers" → "the universal scrapers", "our code templates" → "code templates")
    • Removed redundant articles before proper nouns and service names (e.g., "the Apify Console" → "Apify Console" in some contexts)
    • Changed "to use one of our API clients" → "using one of the API clients"
  • Minor wording improvements:
    • "ultimate flexibility" → "full flexibility"
    • "Ok" → "Okay"
    • Removed incomplete/trailing text in some sections

Files Modified

Changes span across multiple documentation sections:

  • Academy guides (web scraping basics, tutorials, build-and-publish)
  • Platform documentation (proxy, storage, actors, integrations, collaboration)
  • API documentation

Notable Details

  • The changes maintain semantic meaning while improving consistency
  • Em dash to hyphen conversion makes the text more accessible and standardizes punctuation style
  • Article usage changes make the documentation more objective and less possessive in tone

https://claude.ai/code/session_01Re3ixKeyNomxheSkJaD7aW

Apply Apify style guide rules across 115+ documentation files:
- Remove "the" before Apify Console and Apify Store (57 instances)
- Add "the" before Apify platform, SDK, CLI, and API where missing
- Replace "our" with "the", "Apify", or product-focused phrasing
- Replace em dashes (—) and en dashes (–) with " - " in prose
- Fix British spellings: grey→gray, catalogue→catalog
- Capitalize "Actor" when referring to Apify technology
- Remove "Happy scraping/coding!" closings
- Fix "Ok" to "Okay"
- Remove sales language ("ultimate", "state-of-the-art")
- Fix "Javascript" to "JavaScript"

https://claude.ai/code/session_01Re3ixKeyNomxheSkJaD7aW
Copilot AI review requested due to automatic review settings March 16, 2026 13:33
@github-actions github-actions bot added the t-management Issues with this label belong to the CTO or engineering managers. label Mar 16, 2026
@mtrunkat mtrunkat marked this pull request as draft March 16, 2026 13:33
@apify-service-account
Copy link

Preview for this PR was built for commit 20ed593a and is ready at https://pr-2339.preview.docs.apify.com!

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR applies documentation-only copy edits to standardize punctuation (notably replacing em dashes per repo style) and reduce possessive/subjective phrasing by adjusting article/pronoun usage across Platform, Academy, and API docs.

Changes:

  • Replaces em dashes with spaced hyphens (-) for consistency with the documentation style guide.
  • Standardizes article/pronoun usage (e.g., “our” → “the”, “the Apify Console” → “Apify Console” in many places).
  • Includes minor wording and capitalization tweaks for readability and US English consistency.

Reviewed changes

Copilot reviewed 116 out of 116 changed files in this pull request and generated 11 comments.

Show a summary per file
File Description
sources/platform/storage/usage.md Article/terminology tweaks in storage retention instructions.
sources/platform/storage/key_value_store.md Dash/article updates in KVS docs; minor wording changes.
sources/platform/storage/index.md Intro sentence punctuation/article updates for storage section.
sources/platform/storage/dataset.md Minor wording adjustments (articles/possessives).
sources/platform/schedules.md Numeric range punctuation + article wording tweaks.
sources/platform/proxy/your_own_proxies.md Terminology update (“our proxies” → “Apify Proxy”).
sources/platform/proxy/usage.md Wording/punctuation updates across proxy usage content.
sources/platform/proxy/residential_proxy.md Removes “the” before Apify Console in a sentence.
sources/platform/proxy/index.md “our SDKs” → “the Apify SDKs” wording change.
sources/platform/proxy/datacenter_proxy.md Wording changes referencing blog/pricing/Console.
sources/platform/limits.md Removes “our” phrasing in limits section reference.
sources/platform/integrations/workflows-and-notifications/workato.md Updates Discord/support wording to less possessive phrasing.
sources/platform/integrations/workflows-and-notifications/n8n/website-content-crawler.md Removes “the” before Apify Console in setup steps.
sources/platform/integrations/workflows-and-notifications/make/youtube.md Removes “the” before Apify Console in setup steps.
sources/platform/integrations/workflows-and-notifications/make/tiktok.md Removes “the” before Apify Console in setup steps.
sources/platform/integrations/workflows-and-notifications/make/search.md Removes “the” before Apify Console in setup steps.
sources/platform/integrations/workflows-and-notifications/make/maps.md Removes “the” before Apify Console in setup steps.
sources/platform/integrations/workflows-and-notifications/make/llm.md Range punctuation + removes “the” before Apify Console in setup steps.
sources/platform/integrations/workflows-and-notifications/make/instagram.md Removes “the” before Apify Console in setup steps.
sources/platform/integrations/workflows-and-notifications/make/index.md Removes “the” before Apify Console; minor phrasing tweaks.
sources/platform/integrations/workflows-and-notifications/make/facebook.md Removes “the” before Apify Console; minor phrasing tweaks.
sources/platform/integrations/workflows-and-notifications/make/amazon.md Removes “the” before Apify Console in setup steps.
sources/platform/integrations/workflows-and-notifications/make/ai-crawling.md Removes “the” before Apify Console in setup steps.
sources/platform/integrations/workflows-and-notifications/ifttt.md Removes “the” before Apify Console in note text.
sources/platform/integrations/workflows-and-notifications/bubble.md Updates Console/Discord phrasing to less possessive.
sources/platform/integrations/programming/webhooks/actions.md Removes “the” before Apify Console in instructions.
sources/platform/integrations/programming/api.md Rephrases recommendations; removes “the” before Apify Console in places.
sources/platform/integrations/integrate_with_apify.md Removes possessive language (“our platform/users”).
sources/platform/integrations/ai/skyfire.md Removes “the” before Apify Store mention.
sources/platform/integrations/ai/qdrant.md Removes “the” before Apify Console in a sentence.
sources/platform/integrations/ai/pinecone.md Removes “the” before Apify Console in a sentence.
sources/platform/integrations/ai/milvus.md Removes “the” before Apify Console in a sentence.
sources/platform/integrations/ai/haystack.md Minor wording change (removes a phrase repetition).
sources/platform/integrations/actors/integration_ready_actors.md “our example” → “this example” phrasing and possessive removal.
sources/platform/integrations/actors/index.md US English spelling (“catalogue” → “catalog”).
sources/platform/index.mdx Removes “our” from Academy card description.
sources/platform/console/two-factor-authentication.md Removes “our” from support wording + removes “the” before Apify Console.
sources/platform/console/store.md Removes “our community” wording + minor phrasing tweak.
sources/platform/console/settings.md Removes “our platform/docs” wording; minor phrasing tweak.
sources/platform/console/index.md Removes “our verification page”; adjusts homepage intro sentence.
sources/platform/collaboration/organization_account/setup.md “our video tutorial” → “the video tutorial”.
sources/platform/collaboration/organization_account/index.md “our plans/pricing” → “plans/pricing page” phrasing.
sources/platform/collaboration/organization_account/how_to_use.md Removes “the” before Apify Console in header/description.
sources/platform/collaboration/general-resource-access.md Converts dash characters + minor phrasing adjustments.
sources/platform/actors/running/usage_and_resources.md Removes “our article” phrasing.
sources/platform/actors/running/store.md Removes “our Discord” phrasing; removes “the” before Apify Console.
sources/platform/actors/running/index.md Adds article for “the Apify API” heading.
sources/platform/actors/publishing/testing.mdx Removes “our public” phrasing.
sources/platform/actors/publishing/publish.mdx Removes “the” before Apify Console in steps.
sources/platform/actors/publishing/monetize/pay_per_event.mdx Removes “the” before Apify Console; removes “our SDKs/CLI” wording.
sources/platform/actors/publishing/monetize/index.mdx Removes “our” before Terms & Conditions references.
sources/platform/actors/publishing/index.mdx Removes “our blog/Discord” phrasing; minor punctuation fixes.
sources/platform/actors/development/quick-start/start_locally.md Adds “the” before Apify CLI.
sources/platform/actors/development/quick-start/build_with_ai.md Adds “the” before Apify CLI.
sources/platform/actors/development/programming_interface/index.mdx Adjusts “the Apify platform” article usage.
sources/platform/actors/development/programming_interface/environment_variables.md Removes “the” before Apify Proxy in one row; removes “the” before Apify Console in step.
sources/platform/actors/development/permissions/index.md Removes “the” before Apify Console in a sentence.
sources/platform/actors/development/deployment/source_types.md Removes “the” before Apify Console in parenthetical.
sources/platform/actors/development/deployment/index.md Adds “the” before Apify CLI in heading/instructions.
sources/platform/actors/development/deployment/continuous_integration.md “our step-by-step guide” → “the step-by-step guide”.
sources/platform/actors/development/automated_tests.md Numeric range punctuation normalization.
sources/platform/actors/development/actor_definition/output_schema/index.md Removes “the” before Apify Console.
sources/platform/actors/development/actor_definition/input_schema/index.md Removes “the” before Apify Console in sentence.
sources/platform/actors/development/actor_definition/docker.md Removes “our Performance documentation” phrasing.
sources/platform/actors/development/actor_definition/actor_json.md Removes “the” before Apify Console/Store; adds “the” before Apify CLI docs.
sources/api/getting-started.mdx Removes “the” before Apify Console.
sources/academy/webscraping/scraping_basics_python/index.md Em dash → spaced hyphen in intro line.
sources/academy/webscraping/scraping_basics_python/13_platform.md Em dash → spaced hyphen conversions throughout lesson.
sources/academy/webscraping/scraping_basics_python/12_framework.md Em dash → spaced hyphen conversions; minor sentence punctuation.
sources/academy/webscraping/scraping_basics_python/11_scraping_variants.md Em dash → spaced hyphen conversion.
sources/academy/webscraping/scraping_basics_python/10_crawling.md Em dash → spaced hyphen conversion.
sources/academy/webscraping/scraping_basics_python/06_locating_elements.md Em dash → spaced hyphen conversion.
sources/academy/webscraping/scraping_basics_python/02_devtools_locating_elements.md Em dash → spaced hyphen conversions; US spelling “grey” → “gray”.
sources/academy/webscraping/scraping_basics_python/01_devtools_inspecting.md Em dash → spaced hyphen conversions.
sources/academy/webscraping/scraping_basics_legacy/data_extraction/save_to_csv.md Em dash → spaced hyphen conversion.
sources/academy/webscraping/scraping_basics_legacy/crawling/first_crawl.md Em dash → spaced hyphen conversion.
sources/academy/webscraping/scraping_basics_javascript/index.md Em dash → spaced hyphen conversion.
sources/academy/webscraping/scraping_basics_javascript/13_platform.md Em dash → spaced hyphen conversions throughout lesson.
sources/academy/webscraping/scraping_basics_javascript/12_framework.md Em dash → spaced hyphen conversions.
sources/academy/webscraping/scraping_basics_javascript/11_scraping_variants.md Em dash → spaced hyphen conversion.
sources/academy/webscraping/scraping_basics_javascript/10_crawling.md Em dash → spaced hyphen conversion.
sources/academy/webscraping/scraping_basics_javascript/06_locating_elements.md Em dash → spaced hyphen conversion.
sources/academy/webscraping/scraping_basics_javascript/02_devtools_locating_elements.md Em dash → spaced hyphen conversions; US spelling “grey” → “gray”.
sources/academy/webscraping/scraping_basics_javascript/01_devtools_inspecting.md Em dash → spaced hyphen conversions.
sources/academy/webscraping/advanced_web_scraping/crawling/crawling-with-search.md Em dash → spaced hyphen conversions; numeric range punctuation.
sources/academy/webscraping/advanced_web_scraping/crawling/crawling-sitemaps.md “actor” → “Actor” capitalization per terminology.
sources/academy/tutorials/node_js/when_to_use_puppeteer_scraper.md “Ok” → “Okay”; minor article changes.
sources/academy/tutorials/node_js/multiple-runs-scrape.md Adds “the” before Apify CLI; removes possessive language.
sources/academy/tutorials/node_js/how_to_save_screenshots_puppeteer.md Adds “the” before Apify SDK; removes trailing sign-off line.
sources/academy/tutorials/node_js/analyzing_pages_and_fixing_errors.md Em dash → spaced hyphen conversions in bullet list.
sources/academy/tutorials/node_js/add_external_libraries_web_scraper.md Removes trailing sign-off line.
sources/academy/tutorials/api/run_actor_and_retrieve_data_via_api.md Capitalization/term consistency (“Actor”); minor wording.
sources/academy/platform/getting_started/index.md Removes “the” before Apify Console in description + bold intro.
sources/academy/platform/getting_started/creating_actors.md Removes “the” before Apify Console; minor rephrasing.
sources/academy/platform/getting_started/apify_client.md Removes “the” before Apify Console in a sentence.
sources/academy/platform/getting_started/apify_api.md Adjusts image alt text wording re: Apify Console.
sources/academy/platform/getting_started/actors.md Removes “the” before Apify Console in a sentence.
sources/academy/platform/expert_scraping_with_apify/solutions/using_api_and_client.md Capitalization/term consistency (“Actor”).
sources/academy/platform/expert_scraping_with_apify/solutions/integrating_webhooks.md Removes “the” before Apify Console reference.
sources/academy/build-and-publish/why_publish.md Em dash → spaced hyphen conversion.
sources/academy/build-and-publish/promoting-your-actor/seo.md Capitalization consistency (“Actor”).
sources/academy/build-and-publish/promoting-your-actor/blogs_and_blog_resources.md Em dash → spaced hyphen conversions.
sources/academy/build-and-publish/promoting-your-actor/affiliates.md Adds leading article to list item (“The Apify platform”).
sources/academy/build-and-publish/interacting-with-users/emails_to_actor_users.md Em dash → spaced hyphen conversions in tips/examples.
sources/academy/build-and-publish/how-to-build/index.md Removes possessives (“our”); em dash → spaced hyphen; wording tweaks.
sources/academy/build-and-publish/how-to-build/how_to_create_a_great_input_schema.md Em dash → spaced hyphen conversions.
sources/academy/build-and-publish/how-to-build/actorization_playbook.mdx Em dash → spaced hyphen; adds “the” before Apify CLI; wording tweaks.
sources/academy/build-and-publish/how-to-build/actor_bundles.md Em dash → spaced hyphen conversion.
sources/academy/build-and-publish/apify-store-basics/name_your_actor.md Em dash → spaced hyphen conversion.
sources/academy/build-and-publish/apify-store-basics/importance_of_actor_url.md Em dash → spaced hyphen conversion.
sources/academy/build-and-publish/apify-store-basics/how_to_create_actor_readme.md Em dash → spaced hyphen conversions; numeric range punctuation.
sources/academy/build-and-publish/apify-store-basics/how_store_works.md Em dash → spaced hyphen conversion.
sources/academy/build-and-publish/apify-store-basics/how_actor_monetization_works.md Em dash → spaced hyphen conversion.
sources/academy/build-and-publish/actor-ideas/what_software_an_actor_can_be.md Em dash → spaced hyphen conversion.
sources/academy/build-and-publish/actor-ideas/actor_validation.md Em dash → spaced hyphen conversions.
sources/academy/ai/ai-agents.mdx Em dash → spaced hyphen conversion.

You can also share your feedback on Copilot code review. Take the survey.

@mtrunkat mtrunkat marked this pull request as ready for review March 16, 2026 13:45
@mtrunkat mtrunkat added the adhoc Ad-hoc unplanned task added during the sprint. label Mar 16, 2026
@mtrunkat mtrunkat changed the title Standardize article punctuation and article usage feat: Fixing copy using Dave's LLM style guide Mar 16, 2026
Copy link
Contributor

@TC-MO TC-MO left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Few additional issues I noticed, otherwise seems good, thanks! (our style guide for review-docs is also based on Dave LLM's style guide)

@marcel-rbro
Copy link
Contributor

Review findings

Must fix

1. Missing article before "homepage"sources/platform/console/index.md
Changed The Apify Console homepage providesApify Console homepage provides. The "The" modifies "homepage" (the sentence subject), not "Apify Console". Without it, the sentence is grammatically broken. Should be "The Apify Console homepage provides..." or restructured to "The homepage of Apify Console provides...".

2. Missing article before "hostname"sources/platform/proxy/usage.md
Changed the proxy server at the Apify Proxy hostnamethe proxy server at Apify Proxy hostname. Same issue — "the" modifies "hostname", not "Apify Proxy". Should be "at the Apify Proxy hostname".

3. Missing "the" before "API" in front mattersources/platform/collaboration/organization_account/how_to_use.md
Changed description to using Apify Console or API. Per terminology rules, the Apify API requires "the". Should be using Apify Console or the Apify API.

4. Vague "the findings"sources/platform/proxy/usage.md
Changed our findings on how blocking worksthe findings on how blocking works. "The findings" with no prior context is vague. Should be "Apify's findings" to preserve attribution.

5. Lost Apify attribution on Discordsources/academy/platform/get_most_of_actors/monetizing_your_actor.md
Changed Our [Discord community]The [Discord community]. This loses the Apify connection. Should be "The [Apify Discord community]".

Should fix

6. En dashes in numeric ranges replaced with hyphens (systematic, ~8 locations)
The PR replaces en dashes (–) used in numeric ranges like 1–5, 0–9, 100–999, $5–10 with plain hyphens. The style guide prohibits em dashes (—), not en dashes. En dashes are the correct typographic character for ranges. Affected files:

  • how_to_create_actor_readme.md (1–6, 1–2)
  • automated_tests.md (1–5)
  • proxy/usage.md (0–9, 100–999)
  • schedules.md (3–63)
  • make/llm.md (1–100)
  • crawling-with-search.md ($5–10)

7. "state-of-the-art" removed from third-party descriptionsources/platform/integrations/ai/haystack.md
Changed state-of-the-art search systemsadvanced search systems. This describes Haystack (a third-party product), not Apify. The sales language rule applies to Apify marketing, not to how external tools describe themselves.

8. Inconsistent "our" not caughtsources/academy/build-and-publish/how-to-build/actorization_playbook.mdx
While most Actors on our marketplace are web scrapers was left unchanged. Should be "the Apify marketplace" or "the marketplace" for consistency with other "our" → "the" changes in this PR.

9. Inconsistent "our" not caughtsources/academy/build-and-publish/how-to-build/how_to_create_actor_readme.md
our system for Actor recommendation works was left unchanged. Should be "the system" or "Apify's system".

Nitpicks

  • Out-of-scope changes mixed in: greygray, cataloguecatalog, JavascriptJavaScript, actorActor. These are all correct per style guide but weren't listed in the PR description. Not a problem, just worth noting.
  • Change inside HTML comment (what_software_an_actor_can_be.md): An em dash was replaced inside a <!-- --> comment. Harmless but unnecessary.
  • Actor/actor-task inconsistency (run_actor_and_retrieve_data_via_api.md): "Actor" was capitalized but "actor-task" right next to it was left lowercase.

🤖 Generated with Claude Code

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copy link
Contributor

Copilot AI commented Mar 16, 2026

@mtrunkat I've opened a new pull request, #2340, to work on those changes. Once the pull request is ready, I'll request review from you.

Copy link
Contributor

Copilot AI commented Mar 16, 2026

@mtrunkat I've opened a new pull request, #2341, to work on those changes. Once the pull request is ready, I'll request review from you.

@apify-service-account
Copy link

Preview for this PR was built for commit aa1b8c69 and is ready at https://pr-2339.preview.docs.apify.com!

Marcel Rbro and others added 3 commits March 16, 2026 17:29
Remove extra blank lines at EOF in add_external_libraries_web_scraper.md
(fixes MD012 lint failure) and rewrite passive voice in proxy/usage.md
to active voice per style guide.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Line 10 of `sources/platform/proxy/usage.md` was missing the article
"the" before "Apify Proxy hostname", making the sentence ungrammatical.

- **`sources/platform/proxy/usage.md`**: `at Apify Proxy hostname` → `at
the Apify Proxy hostname`

<!-- START COPILOT CODING AGENT TIPS -->
---

🔒 GitHub Advanced Security automatically protects Copilot coding agent
pull requests. You can protect all pull requests by enabling Advanced
Security for your repositories. [Learn more about Advanced
Security.](https://gh.io/cca-advanced-security)

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mtrunkat <594801+mtrunkat@users.noreply.github.com>
"Apify Console homepage provides..." was missing the leading article,
resulting in awkward phrasing.

- **`sources/platform/console/index.md`**: Changed "Apify Console
homepage provides..." → "The Apify Console homepage provides..."

<!-- START COPILOT CODING AGENT TIPS -->
---

📱 Kick off Copilot coding agent tasks wherever you are with [GitHub
Mobile](https://gh.io/cca-mobile-docs), available on iOS and Android.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mtrunkat <594801+mtrunkat@users.noreply.github.com>
@apify-service-account
Copy link

Preview for this PR was built for commit 57a4d5f8 and is ready at https://pr-2339.preview.docs.apify.com!

mtrunkat and others added 4 commits March 17, 2026 08:29
Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>
Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>
- Restore en dashes in numeric ranges (style guide prohibits em dashes, not en dashes)
- Fix "the findings" to "Apify's findings" for proper attribution
- Fix "our marketplace" to "Apify Store" and "our system" to "Apify's system"
- Revert "state-of-the-art" for Haystack (third-party product description)
- Add "the" before "Apify API" in how_to_use.md frontmatter
- Remove trailing whitespace in general-resource-access.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@apify-service-account
Copy link

Preview for this PR was built for commit 57a4d5f8 and is ready at https://pr-2339.preview.docs.apify.com!

@apify-service-account
Copy link

Preview for this PR was built for commit fc183380 and is ready at https://pr-2339.preview.docs.apify.com!

@mtrunkat mtrunkat requested a review from TC-MO March 17, 2026 07:53
@apify-service-account
Copy link

Preview for this PR was built for commit 1bfebbc4 and is ready at https://pr-2339.preview.docs.apify.com!

@apify-service-account
Copy link

Preview for this PR was built for commit 546e8d7f and is ready at https://pr-2339.preview.docs.apify.com!

@marcel-rbro marcel-rbro changed the title feat: Fixing copy using Dave's LLM style guide docs: Fix copy using Dave's LLM style guide Mar 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

adhoc Ad-hoc unplanned task added during the sprint. t-management Issues with this label belong to the CTO or engineering managers.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants