Skip to content

docs: enrich Actor development pages from help-center articles - #2826

Open
marcel-rbro wants to merge 10 commits into
masterfrom
docs/helpcenter-actor-dev
Open

docs: enrich Actor development pages from help-center articles#2826
marcel-rbro wants to merge 10 commits into
masterfrom
docs/helpcenter-actor-dev

Conversation

@marcel-rbro

Copy link
Copy Markdown
Contributor

Salvages still-useful content from four retiring help-center articles into the platform docs, so the information survives the help-center wind-down and lives in one place.

  • Continuous integration: replaces the outbound "Bitbucket CI guide" link with an in-page Bitbucket Pipelines section (modernized YAML on node:22, secured APIFY_TOKEN, tests before push, branch-based build tags).
  • Usage and resources: adds reference compute-unit rates and a test-run method for estimating consumption, and repoints the two former help-center links in-page.
  • Builds: adds a versioning best-practices subsection for public Actors.
  • Monetize: adds a section on compensating users for failed runs with platform credits.

Part of the help-center audit; a companion PR covers the Integrations articles.

Salvage still-useful content from four retiring help-center articles into
the platform docs:

- Continuous integration: replace the outbound Bitbucket CI link with an
  in-page Bitbucket Pipelines section (modernized YAML, secured token,
  tests before push, branch-based build tags).
- Usage and resources: add reference compute-unit rates and a test-run
  method for estimating consumption; repoint the two help-center links
  in-page.
- Builds: add a versioning best-practices subsection for public Actors.
- Monetize: add a section on compensating users for failed runs with
  platform credits.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@marcel-rbro marcel-rbro added documentation Improvements or additions to documentation. t-docs Issues owned by technical writing team. labels Jul 28, 2026
@marcel-rbro marcel-rbro self-assigned this Jul 28, 2026
@apify-service-account

apify-service-account commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

✅ Preview for this PR (commit e32f633d) is ready at https://pr-2826.preview.docs.apify.com (see action run).

marcel-rbro and others added 8 commits July 28, 2026 11:42
Split over-long sentences, fix passive voice and bold UI element,
trim link filler, and expand two short frontmatter descriptions into
the 140-160 char range, per the review-docs standards checks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rephrase the monetize description to drop an unquoted colon that broke
front matter parsing, and remove a stray thematic break that rendered
as a horizontal rule under the continuous-integration title.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move the GitHub integration method ahead of Bitbucket Pipelines in both
the methods list and the section order, grouping the GitHub-based
options together.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a short lead-in that frames what the page covers - resource
allocation, compute units, and estimating and reducing usage - instead
of opening straight into the Resources heading.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rename the vague "Requirements" H2 to "Choose the right memory" to
describe what the section is for, and pair its subsections as "Minimum
memory" and "Maximum memory" so the page reads resources -> sizing ->
usage. No inbound links referenced the renamed anchors.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a short lead-in that defines a build and frames the page - builds
and build numbers, versioning and tags, and the build cache - instead
of opening straight into a heading.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document that developers request a credit compensation from the Apify
support chat via the Request user credit compensation option, add the
screenshot showing it, and clarify that the compensated amount is
deducted from the developer's payout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Render the tall portrait screenshot with the repo's sized-image pattern
at a fixed 320px width so it no longer dominates the page.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@marcel-rbro
marcel-rbro marked this pull request as ready for review July 28, 2026 14:34
Replace the PNG with an optimized WebP (259 KB -> 52 KB) and update the
reference, fixing the Lint images CI check.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

## Compensate users for failed runs

If a run fails or returns bad results because of a problem with your Actor, you can compensate the affected user with Apify platform credits. The amount is deducted from your payout.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think the content team said that using "credits" is a no-no, and that we should use "prepaid usage". Verify.


<img src={require('./images/request-user-credit-compensation.webp').default} alt="The Request user credit compensation option in the Apify support chat" width="320" />

The **Request user credit compensation** option appears in the Apify support chat only for Actor developers. If you're contacting support as a user, you won't see it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

If you're contacting support as a user
This feels a bit awkward - aren't they all users? How do you distinguish them?
Technically, it works based on whether they currently have any public Actor in Store.


The **Request user credit compensation** option appears in the Apify support chat only for Actor developers. If you're contacting support as a user, you won't see it.

Keep a few things in mind when handling compensations:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I do think that this section is quite simplified and the "How to talk about compensation" section in Help Center is more descriptive for the publisher. Since they'll be scanning this info, chances are that they'll skip these three bullet points altogether. Since we've had quite a lot of problems with this, it deserves much bigger space and attention.

@tomnosek

tomnosek commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

I've left a couple of comments (not a proper review though, just a random stumble), but my overall impression is that it expands a subpar page, creating even more subpar page 😄 The page is sort of like an incoherent reference jumping from topic to topic.

A couple of points:

  • It's in the Actors > Running Actors section, so the target audience is also common users. Yet it starts by saying Actors run in Docker containers. How is that important to this topic?
  • After the leading paragraph, we get the heading "Resources"... in an article already named "Usage and resources". I don't even know what you mean by it, and I've already read it twice as headings in 5 rows.
  • It says about the memory that "It must be a power of 2." but it was recently changed to a drop-down menu, so it's not an important info anymore (and for dynamic memory, it's written in the dynamic memory page).
  • In the middle, there's a section about Crawlee... If I'm a user, I'm like "What the F is Crawlee?" There could be a callout, but it's quite irrelevant for the broad audience, so it shouldn't be part of the main content.
  • The "What is a compute unit" is in the middle, yet half of the page above talks about "CUs" and often doesn't even reference this part.
  • The "What determines consumption" section suddenly talks about Playwright and Cheerio. Again, as a user, I'm completely confused.

This page jumps from topic to topic, talks about terms that I don't understand as a reader, and in the end, I feel like I haven't learned anything. With a certain level of skimming, I certainly can't configure the Run options part properly. So, I think the page should be just completely rewritten.

(Btw. I know that this commit is not adding the whole page and that it was created in the past likely in many iterations, but let's end up with a better page, not just mixing more confusion in this confusion pot.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation. t-docs Issues owned by technical writing team.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants