diff --git a/sources/academy/build-and-publish/apify-store-basics/how_actor_monetization_works.md b/sources/academy/build-and-publish/apify-store-basics/how_actor_monetization_works.md index b9796d88b1..8080c085d7 100644 --- a/sources/academy/build-and-publish/apify-store-basics/how_actor_monetization_works.md +++ b/sources/academy/build-and-publish/apify-store-basics/how_actor_monetization_works.md @@ -126,7 +126,7 @@ Also, remember that your Actor is a package deal with the Apify platform. All th Apify Store is like any other marketplace, so take a look at your competition there. Are you the first in your lane, or are there other similar tools? What makes yours stand out? Remember, your README is your first impression - communicate your tool's benefits clearly and offer something unique. Competing with other developers is great, but collaborations can drive even better results šŸ˜‰ -Learn more about what makes a good readme here: [How to create an Actor README](/academy/actor-marketing-playbook/actor-basics/how-to-create-an-actor-readme) +Learn more about what makes a good readme: [Create an Actor README](/actors/publishing/actor-readme). ### Adapt when needed diff --git a/sources/academy/build-and-publish/apify-store-basics/how_to_create_actor_readme.md b/sources/academy/build-and-publish/apify-store-basics/how_to_create_actor_readme.md deleted file mode 100644 index f324a77f34..0000000000 --- a/sources/academy/build-and-publish/apify-store-basics/how_to_create_actor_readme.md +++ /dev/null @@ -1,268 +0,0 @@ ---- -title: How to create an Actor README -description: Learn how to write a comprehensive README to help users better navigate, understand and run public Actors in Apify Store. -sidebar_position: 5 -category: build-and-publish -slug: /actor-marketing-playbook/actor-basics/how-to-create-an-actor-readme ---- - -**Learn how to write a comprehensive README to help users better navigate, understand and run public Actors in Apify Store.** - ---- - -## What's a README in the Apify sense? - -At Apify, when we talk about a README, we donā€™t mean a guide mainly aimed at developers that explains what a project is, how to set it up, or how to contribute to it. At least, not in its traditional sense. - -You could argue our notion of README is closer to this [one described on GitHub](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes): - -README files typically include information on: - -- What the project does -- Why the project is useful -- How users can get started with the project -- Where users can get help with your project - -We mean all of this and even more. At Apify, when we talk about READMEs, we refer to the public Actor detail page on Apify Store. Specifically, its first tab. The README exists in the same form both on the web and in Console. What is it for then? - -Before we dive in, a little disclaimer: you don't need your Apify README to fulfill all its purposes. Technically, you could even publish an Actor with just a single word in the README. But you'd be missing out if you did that. - -Your Actorā€™s README has at least four functions: - -1. _SEO_ - If your README is well-structured and includes important keywords - both in headings and across the text - it has a high chance of being noticed and promoted by Google. Organic search brings the most motivated type of potential users. If you win this game, you've won most of the SEO game. -2. _First impression_ - Your README is one of the first points of contact with a potential user. If you come across as convincing, clear, and reassuring it could be the factor that will make a user try your Actor for their task. -3. _Extended instruction_ - The README is also the space that explains specific complex input settings. For example, special formatting of the input, any coding-related, or extended functions. Of course, you could put that all in a blog post as well, but the README should be their first point of contact. -4. _Support_ - Your users come back to the README when they face issues. Use it as a space to let them know that's where they can find links to the tutorials if they run into issues, describe common troubleshooting techniques, share tricks, or warn you about bugs. - -## README elements theory - -These are the most important elements of the README. This structure is also not to be followed to a ā€œtā€. Of course, what you want to say to your potential users and how you want to promote your Actor will differ case by case. These are just the most common practices we have for our Actor READMEs. Beware that the headings are written with SEO in mind, which is why you see certain keywords repeated over and over. - -Aim for sections 1ā€“6 below and try to include at least 300 words. You can move the sections around to some extent if it makes sense, e.g. 3 might come after 6. Consider using emojis as bullet points or otherwise trying to break up the text. - -### Intro and features - -What is [Actor]? - -- explain in two or three sentences what the Actor does and the easiest way to try it. Mention briefly what kind of data it can extract and any other tangible goal the tool can achieve. Describe the input in one sentence. Highlight the most important words in bold. - -What can this [Actor] do? - -- list the main features of this tool. list multiple ways of input if applicable. list platform advantages. If it's a bundle, mention the steps that the Actor will do for you, mention specific obstacles this tool is able to overcome, say upfront how many results you can get for free. - -:::tip Remember the Apify platform! - -Your Actor + the Apify platform. They come as a package. Don't forget to flaunt all the advantages that the platform gives to your solution. - -::: - -Imagine if there was a solution that is identical to yours but without the platform advantages such as monitoring, access to API, scheduling, possibility of integrations, proxy rotation. Now, if that tool suddenly gained all those advantages it would surely make a selling point out of it. This is how you should be thinking about your tool - as a solution boosted by the Apify platform. Don't ever forget that advantage. - -What data can [Actor] extract? - -What data can you extract from [target website] - -- Create a table that represents the main data points that the Actor can extract. You don't have to list every single one, just list the most understandable and relatable ones. - -Depending on the complexity of your Actor, you might include one or all three of these sections. It will also depend on what your Actor does. If your Actor has simple input but does a lot of steps for the user under the hood (like a bundle would), you might like to include the "What can this Actor do?" section. If your Actor extracts data, it makes sense to include a section with a table. - -### Tutorial section - -This could be a simple listed step-by-step section or a paragraph with a link to a tutorial on a blog. - -A step-by-step section is reassuring for the user, and it can be a section optimized for Google. - -How do I use [Actor] to scrape website data? - -### Pricing - -How much will it cost to scrape [target site]? - -How much will scraping [target site] cost? - -Is scraping [target site] free? - -How much does it cost to extract [target site] data? - -Web scraping can be very unpredictable because there are a lot of elements involved in order for the process to be successful: the complexity of the website, proxies, cookies, etc. This is why it's important to set the pricing and scraping volume expectations for your users. - -You might think the part above the Actor detail page already indicates pricing. But this paragraph can still be useful. First of all, cost-related questions can show up in Google, if they are SEO optimized. Second, you can use this space to inform and reassure the user about the pricing, give more details about it, or entice them with the promise of very scalable scraping. - -- If it's a consumption pricing model (only consumed CUs), you can use this space to set expectations and explain what it means to pay for Compute Units. Similarly, if it's a rental Actor, you can also use this paragraph to set expectations. Talk about the average amount of data that can be scraped per given price. Make it easy for users to imagine how much they will pay for a given dataset. This will also make it easier for them to compare your solution with others on the market price-wise and value-wise. -- If it's price per result, you can extrapolate how many results a user can get on a free plan and also entice them with a larger plan and how many thousands of results they can get with that. -- If it's a bundle that consists of a couple of Actors that are priced differently, you can use this section to talk about the difference between all the Actors involved and how that will affect the final price of a run. - -In any case, on top of setting expectations and reassuring users, this paragraph can get into Google. If somebody is Googling "How much does it cost to scrape [website]", they might come across this part of your README and it will lead them from Google search directly to your Actor's detail page. You don't want to miss that opportunity. - -![readme example](images/readme.png) - -### Input and output examples - -This is what people click on the most in the table of contents of the README. After they are done scrolling through the first part of the README, users are interested in how difficult the input it, what it looks like, and what kind of information they can expect. - -**Input**: often a screenshot of the input schema. This is also a way for people to see the platform even before they create an account. - -**Output**: can be shown as a screenshot if your output schema looks like something you would want to promote to users. You can also just include a JSON example containing a few objects. Even better if there's continuity between the input example and output example. - -If your datasets come out too complex and you want to save your users some scrolling, you can also show multiple output examples: one for reviews, one for contact details, one for ads, etc. - -### Other Actors - -Don't forget to promote your other Actors. While Apify's system for Actor recommendation works - you can see related Actors at the bottom of the README - it only works within the same category or similar name. It won't recommend a completely different Actor from the same creator. Make sure to interconnect your work by taking the initiative yourself. You can mention your other Actors in a list or as a table. - -### FAQ, disclaimers, and support - -The FAQ is a section where you can keep all the secondary questions that might still come up. - -Here are just a few things we usually push to the FAQ section. - -- disclaimers and legality -- comparison table between your Actor and similar solutions -- information about the official API and how the scraper is a stand-in for it (SEO) -- questions brought up by the users -- tips on how best to use the Actor -- troubleshooting and mentioning known bugs -- mentioning the Issues tab and highlighting that you're open for feedback and collecting feedback -- mentioning being open to creating a custom solution based on the current one and showing a way to contact you -- interlinking -- mentioning the possibility of transferring data using an API - API tab -- possibility for integrations -- use cases for the data scraped, success stories exemplifying the use of data - -## Format of the README - -### Markdown - -The README has to be written in Markdown. The most important elements are H2 and H3 headings, links to pages, links to images, and tables. For specific formatting, you can try using basic HTML. That will also work. CSS wonā€™t. - -### HTML use - -You can mix HTML with Markdown interchangeably. The Actor README will display either on the Apify platform. That gives you more freedom to use HTML when needed. Remember, don't try CSS. - -### Tone of the README - -Apify Store has many Actors in its stock, and it's only growing. The advantage of an Actor is that an Actor can be anything, as versatile or complex as possible. From a single URL type of input to complex features that give customized control over the input parameters to the user. There are Actors that are intended for users who aren't familiar with coding and don't have any experience with it. Ideally, the README should reflect the level of skill one should need to use the Actor. - -The tone of the README should make it immediately obvious who the tool is aimed at. If your tool's input includes glob patterns or looking for selectors, it should be immediately visible from the README. Before the user even tries the tool. Trying to simplify this information using simple words with ChatGPT can be misleading to the user. You will attract the wrong audience, and they will end up churning or asking you too many questions. - -And vice versa. If your target audience is people with little to no coding skills, who just prefer point-and-click solutions, this should be visible from the README. Speak in regular terms, avoid code blocks or complex information at the beginning unless it's absolutely necessary. This means that, when people land on your Actor detail page, they will have their expectations set from the get-go. - -### Length of a README - -When working on improving a README, we regularly look at heatmaps that show us where our website visitors spend most of their time. From our experience, most first-time visitors don't scroll past the first 25% of a README. That means that the first quarter of the README is where you want to focus the most of your attention if you're trying to persuade the page visitor to try your Actor. - -From the point of view of acquisition, the first few sections should make it immediately obvious what the tool is about, how hard it is to use, and who it is created for. This is why, in Apify's READMEs, you can see our first few paragraphs are built in such a way as to explain these things and reassure the visitors that anyone can use these tools. - -From the point of view of retention, it doesn't mean you can't have long or complex READMEs or not care for the information beyond the 25% mark. Since the README is also intended to be used as a backup when something goes wrong or the user needs more guidance, your users will come back to it multiple times. - -### Images and videos - -As for using screenshots and gifs, put them in some sort of image hosting. Your own GitHub repository would be best because you have full control over it. Name the images with SEO in mind and try to keep them compressed but good enough quality. You don't want to load an image or gif for too long. - -One trick is not only to add images but also to make them clickable. For some reason, people like clicking on images, at least they try to when we look at the heatmaps. You can lead the screenshot clicks towards a signup page, which is possible with Markdown. - -If your screenshot seems too big or occupies too much space, smaller size images are possible by using HTML. - -To embed a YouTube video, all you have to do is include its URL. No further formatting is needed, the thumbnail will render itself on the README page. - -:::tip Try Carbon for code - -If you want to add snippets of code anywhere in your README, you can useĀ [Carbon](https://github.com/carbon-app/carbon). - -::: - -If you need quick Markdown guidance, check outĀ [https://www.markdownguide.org/cheat-sheet/](https://www.markdownguide.org/cheat-sheet/) - - -## README and SEO - -Your README is your landing page. - -If there were only one thing to remember about READMEs on Apify Store, it would be this. A README on Apify Store is not just dry instructions on how to use your Actor. It has much more potential than that. - -In the eyes of Google, your Actor's detail page, aka README, is a full-fledged landing page containing all the most important information to be found and understood by users. - -Of course, that all only counts if your README is both well formatted and contains keywords. We'll talk about that part later on. - -What makes a good README? - -A good README has to be a balance between what you want your page visitors to know, your users to turn to when they run into trouble, and Google to register when it's indexing pages and considering which one deserves to be put up higher. - -### Table of contents - -The H1 of your page is the Actor name, so you don't have to set that up. Don't add more H1s. README headings should be H2 or H3. H2 headings will make up the table of contents on the right. If you don't want the table to be too crowded, keep the H2s to the basics and push all the longer phrases and questions to H3s. H3s will stay hidden in the accordion in the default state until the visitor hovers their cursor over it. H4 readings can also be included, of course, but they won't show up as a part of the table of contents. - -### Keyword opportunities - -Do SEO research for keywords and see how they can fit organically into the text. Priority for H2s and H3s, then the regular text. Add new keyword-heavy paragraphs if you see an opportunity. - -The easiest sections to include keywords in are, for example: - -- API, as in Instagram API -- data, as in extract Instagram data -- Python, as in extract data in Python -- scrape, as in how to scrape X -- scraping, as in scraping X - -Now, could every H2 just say exactly what it is about, without SEO? Of course. You don't have to optimize your H2s and H3s, and are free to call them simply Features, How it works, Pricing, Support, etc. or not even to have many H2s at all and keep it all as one page. - -However, the H2s and H3s are what sometimes get into the Google Search results. If you're familiar with the People Also Ask section, that's the best place to match your H2s. They can also get highlighted in the Sitelinks of Google Search Results. - -Any part of your README can make it onto Google pages. The intro sentence describing what your Actor is about, a video, a random question. Each one can become a good candidate for those prime Google pages. That's why it's important to structure and write your README with SEO in mind. - -### Importance of including a video - -If your page has a video, it has a better chance of ranking higher in Google. - -## README and input schema - -The README should serve as a fallback for your users if something isn't immediately obvious in the input schema. There's also only that much space in the input schema and the tooltips, so naturally, if you want to provide more details about something, e.g. input, formatting, or expectations, you should put it in the README and refer to it from the relevant place in the input schema. - -Learn about [How to create a great input schema](/academy/actor-marketing-playbook/product-optimization/how-to-create-a-great-input-schema) - -## Readme elements template - -1. What does (Actor name) do? - - in 1ā€“2 sentences describe what the Actor does and what it does not do - - consider adding keywords like API, e.g. Instagram API - - always have a link to the target website in this section -2. Why use (Actor name)? or Why scrape (target site)? - - How it can be beneficial for the user - - Business use cases - - Link to a success story, a business use case, or a blog post. -3. How to scrape (target site) - - Link to "How toā€¦" blogs, if one exists (or suggest one if it doesn't) - - Add a video tutorial or gif from an ideal Actor run. - -:::tip Embedding YouTube videos - -For better user experience, Apify Console automatically renders every YouTube URL as an embedded video player. Simply add a separate line with the URL of your YouTube video. - -::: - -- Consider adding a short numbered tutorial, as Google will sometimes pick these up as rich snippets. Remember that this might be in search results, so you can repeat the name of the Actor and give a link, e.g. - -1. Is it legal to scrape (target site)? - - This can be used as a boilerplate text for the legal section, but you should use your own judgment and also customize it with the site name. - - > Our scrapers are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our scrapers, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by theĀ GDPRĀ in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers. You can also read our blog post on theĀ legality of web scraping - > -2. Input - - Each Actor detail page has an input tab, so you just need to refer to that. If you like, you can add a screenshot showing the user what the input fields will look like. - - This is an example of how to refer to the input tab: - - > Twitter Scraper has the following input options. Click on theĀ input tabĀ for more information. - > -3. Output - - Mention "You can download the dataset extracted by (Actor name) in various formats such as JSON, HTML, CSV, or Excel.ā€ - - Add a simplified JSON dataset example, like hereĀ https://apify.com/compass/crawler-google-places#output-example -4. Tips or Advanced options section - - Share any tips on how to best run the Actor, such as how to limit compute unit usage, get more accurate results, or improve speed. - -If you want some general tips on how to make a GitHub README that stands out, check out these guides. Not everything in there will be suitable for an Apify Actor README, so you should cherry-pick what you like and use your imagination. - -## Resources - -[Build a Stunning README For Your GitHub Profile](https://towardsdatascience.com/build-a-stunning-readme-for-your-github-profile-9b80434fe5d7) - -[How to Create a Beautiful README for Your GitHub Profile](https://yushi95.medium.com/how-to-create-a-beautiful-readme-for-your-github-profile-36957caa711c) diff --git a/sources/academy/build-and-publish/apify-store-basics/images/readme.png b/sources/academy/build-and-publish/apify-store-basics/images/readme.png deleted file mode 100755 index 2ac7acc79c..0000000000 Binary files a/sources/academy/build-and-publish/apify-store-basics/images/readme.png and /dev/null differ diff --git a/sources/academy/build-and-publish/how-to-build/actorization_playbook.mdx b/sources/academy/build-and-publish/how-to-build/actorization_playbook.mdx index d575473f28..2946f26f19 100644 --- a/sources/academy/build-and-publish/how-to-build/actorization_playbook.mdx +++ b/sources/academy/build-and-publish/how-to-build/actorization_playbook.mdx @@ -137,6 +137,6 @@ Deployment to the Apify platform can be done easily via `apify push` command of ### 6. Publish and monetize -For details on publishing the Actor in [Apify Store](https://apify.com/store) see the [Publishing and monetization](/actors/publishing). You can also follow the guide on [How to create an Actor README](/academy/actor-marketing-playbook/actor-basics/how-to-create-an-actor-readme) and [Marketing checklist](/academy/actor-marketing-playbook/promote-your-actor/checklist). +For details on publishing the Actor in [Apify Store](https://apify.com/store) see the [Publishing and monetization](/actors/publishing). You can also follow the guide on how to [Create an Actor README](/actors/publishing/actor-readme) and [Marketing checklist](/academy/actor-marketing-playbook/promote-your-actor/checklist). To show your Actor's current status and usage in your README or documentation, add the [Actor status badge](/actors/publishing/status-badge). diff --git a/sources/platform/actors/development/actor_definition/actor_json.md b/sources/platform/actors/development/actor_definition/actor_json.md index 9338a1ed95..b9e13e0e89 100644 --- a/sources/platform/actors/development/actor_definition/actor_json.md +++ b/sources/platform/actors/development/actor_definition/actor_json.md @@ -79,7 +79,7 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on | `environmentVariables` | Optional | A map of environment variables to be used during local development. These variables will also be applied to the Actor when deployed on the Apify platform. For more details, see the [environment variables](/cli/docs/vars) section of the Apify CLI documentation. | | `dockerfile` | Optional | The path to the Dockerfile to be used for building the Actor on the platform. If not specified, the system will search for Dockerfiles in the `.actor/Dockerfile` and `Dockerfile` paths, in that order. Refer to the [Dockerfile](./docker.md) section for more information. | | `dockerContextDir` | Optional | The path to the directory to be used as the Docker context when building the Actor. The path is relative to the location of the `actor.json` file. This property is useful for monorepos containing multiple Actors. Refer to the [Actor monorepos](../deployment/source_types.md#actor-monorepos) section for more details. | -| `readme` | Optional | The path to the README file to be used on the platform. If not specified, the system will look for README files in the `.actor/README.md` and `README.md` paths, in that order of preference. Check out [Apify Marketing Playbook to learn how to write a quality README files](https://apify.notion.site/How-to-create-an-Actor-README-759a1614daa54bee834ee39fe4d98bc2) guidance. | +| `readme` | Optional | The path to the README file to be used on the platform. If not specified, the system will look for README files in the `.actor/README.md` and `README.md` paths, in that order of preference. For details, see [Create an Actor README](/actors/publishing/actor-readme). | | `input` | Optional | You can embed your [input schema](./input_schema/index.md) object directly in `actor.json` under the `input` field. You can also provide a path to a custom input schema. If not provided, the input schema at `.actor/INPUT_SCHEMA.json` or `INPUT_SCHEMA.json` is used, in this order of preference. You can also use the `inputSchema` alias interchangeably. | | `output` | Optional | You can embed your [output schema](./output_schema/index.md) object directly in `actor.json` under the `output` field. You can also provide a path to a custom output schema. [Read more](/actors/development/actor-definition/output-schema) about Actor output schemas. You can also use the `outputSchema` alias interchangeably. | | `changelog` | Optional | The path to the CHANGELOG file displayed in the Information tab of the Actor in Apify Console next to Readme. If not provided, the CHANGELOG at `.actor/CHANGELOG.md` or `CHANGELOG.md` is used, in this order of preference. Your Actor doesn't need to have a CHANGELOG but it is a good practice to keep it updated for published Actors. | diff --git a/sources/platform/actors/publishing/images/actor-display-information.webp b/sources/platform/actors/publishing/images/actor-display-information.webp deleted file mode 100644 index 0dcc3cd99d..0000000000 Binary files a/sources/platform/actors/publishing/images/actor-display-information.webp and /dev/null differ diff --git a/sources/platform/actors/publishing/images/actor-page.webp b/sources/platform/actors/publishing/images/actor-page.webp deleted file mode 100644 index d627a3afa2..0000000000 Binary files a/sources/platform/actors/publishing/images/actor-page.webp and /dev/null differ diff --git a/sources/platform/actors/publishing/images/apify-store.webp b/sources/platform/actors/publishing/images/apify-store.webp deleted file mode 100644 index 2698f5b345..0000000000 Binary files a/sources/platform/actors/publishing/images/apify-store.webp and /dev/null differ diff --git a/sources/platform/actors/publishing/images/publish-actor-to-store.webp b/sources/platform/actors/publishing/images/publish-actor-to-store.webp deleted file mode 100644 index af5e951a5e..0000000000 Binary files a/sources/platform/actors/publishing/images/publish-actor-to-store.webp and /dev/null differ diff --git a/sources/platform/actors/publishing/index.mdx b/sources/platform/actors/publishing/index.mdx index 57db42c5ff..4f3a4ca9d8 100644 --- a/sources/platform/actors/publishing/index.mdx +++ b/sources/platform/actors/publishing/index.mdx @@ -55,7 +55,7 @@ While refactoring and updating your Actor's code is encouraged, be cautious of m ### Documentation and testing -Pay special attention to your Actor's documentation ([README](https://apify.notion.site/How-to-create-an-Actor-README-759a1614daa54bee834ee39fe4d98bc2)). It should be clear, detailed, concise and, readable, using simple language and avoiding technical jargon whenever possible, as your users may not be developers. +Pay special attention to your Actor's documentation ([README](/actors/publishing/actor-readme)). It should be clear, detailed, concise and, readable, using simple language and avoiding technical jargon whenever possible, as your users may not be developers. Ensure periodic testing, either manually or by [setting up automatic testing](../development/automated_tests.md) and [monitoring](https://apify.com/apify/monitoring). This can help prevent users from encountering issues with your Actor. diff --git a/sources/platform/actors/publishing/publish-task.mdx b/sources/platform/actors/publishing/publish-task.mdx index 616bb18152..ca7ca87c9e 100644 --- a/sources/platform/actors/publishing/publish-task.mdx +++ b/sources/platform/actors/publishing/publish-task.mdx @@ -13,7 +13,7 @@ You can create up to 50 tasks per Actor. Before you publish a task, make sure you have: -- A [published Actor](./publish.mdx) that you own or maintain. +- A [published Actor](./publish/index.mdx) that you own or maintain. - A [saved task](/actors/running/tasks) with a complete input configuration. - An [input schema](/actors/development/actor-definition/input-schema) and at least one [dataset schema view](/storage/dataset-schema) defined on the Actor. diff --git a/sources/platform/actors/publishing/publish.mdx b/sources/platform/actors/publishing/publish.mdx deleted file mode 100644 index c6db8d6b61..0000000000 --- a/sources/platform/actors/publishing/publish.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Publish your Actor -description: Prepare your Actor for Apify Store by completing the description, README, and display fields, then publish it to make it available to the public. -slug: /actors/publishing/publish -sidebar_position: 1 ---- - -Before making your Actor public, it's important to ensure your Actor has a clear **Description** and comprehensive **README** section. This will help users understand your Actor's purpose, how to configure its inputs, and the type of output it generates. This guide we'll review the essential fields you must complete before publishing your Actor. For more detailed information on [SEO & promotion](https://apify.notion.site/SEO-990259fe88a84fd0a85ce6d3b394d8c1) and [how to write a comprehensive README](https://apify.notion.site/How-to-create-an-Actor-README-759a1614daa54bee834ee39fe4d98bc2),refer to guides available at the [Apify Marketing Playbook](https://apify.notion.site/3fdc9fd4c8164649a2024c9ca7a2d0da?v=6d262c0b026d49bfa45771cd71f8c9ab). - -## Make your Actor public - -Once you've finished coding and testing your Actor, it's time to publish it. Follow these steps: - -1. From your Actor's page in Apify Console, go to **Publication** > **Display information** -2. Fill in all the relevant fields for your Actor (e.g., **Icon**, **Actor name**, **Description**, **Categories**) -3. Save your changes - -![Actor settings](./images/actor-display-information.webp) - -After filling in all the required fields, the **Publish to Store** button will turn green. Click on it to make your Actor available to the public on Apify Store. - -![Publish your Actor](./images/publish-actor-to-store.webp) - -To verify that your Actor has been published successfully, go to the [Apify Store](https://apify.com/store), search for your Actor's name. Click on your Actor's card, to view its dedicated page. This is the page where users will likely have their first interaction with your Actor, so carefully review it and ensure everything is set up correctly. - -![Apify Store](./images/apify-store.webp) - -![Actor page](./images/actor-page.webp) - -### Logo - -We strongly recommend adding a unique image to your Actor that visually represents the service it provides. This helps users quickly understand its purpose. However, do not use official logos or branded images from the sites you're scraping, as this can lead to copyright or trademark issues. - -### Description - -The Actor's description is a short paragraph that explains its purpose. It will be displayed on the Actor's page, right below its title. - -![Actor title and description](./images/actor-title-description.webp) - -When writing your Actor's description, you also have the option to provide an SEO title & description. These will be used in search engine result pages instead of Actor's name & description. Effective SEO titles & descriptions should: - -- Utilize popular keywords related to your Actor's functionality -- Summarize the Actor's purpose concisely -- Be between _40_ to _50_ characters for the title and _140_ to _156_ characters for description - -![SEO title and description](./images/actor-SEO.webp) - -### README - -The next step is to include a comprehensive **README** detailing your Actor's features, reasons for scraping the target website, and instructions on how to use the Actor effectively. - -Remember that the Actor's README is generated from your `README.md` file, and you can apply the same [SEO principles](https://apify.notion.site/SEO-990259fe88a84fd0a85ce6d3b394d8c1) mentioned earlier to optimize you README for search engines. - -To save time when writing your Actor's README, you can use the following template as a starting point: - -https://github.com/zpelechova/readme-template - -Note that the complexity of your README should match the complexity of your Actor. Feel free to adapt the template to fit your Actor's specific requirements. - -## Source code visibility - -When you publish an Actor, its source code files and non-secret [environment variables](/actors/development/programming-interface/environment-variables) are publicly visible by default on the Actor detail page. - -To hide them, go to your Actor's **Settings** tab in Apify Console and check **Hide source files from Actor detail**. Secret environment variables are never exposed regardless of this setting. diff --git a/sources/platform/actors/publishing/publish/actor-readme.mdx b/sources/platform/actors/publishing/publish/actor-readme.mdx new file mode 100644 index 0000000000..cad92b0452 --- /dev/null +++ b/sources/platform/actors/publishing/publish/actor-readme.mdx @@ -0,0 +1,183 @@ +--- +title: Create an Actor README +description: Learn how to create a README for your Actor. +slug: /actors/publishing/actor-readme +sidebar_position: 1 +--- + +Your Actor's README has four functions: + +- SEO. A well-structured README that includes important keywords has a high chance of being noticed and promoted by search engines. Organic search brings the most motivated type of potential users. +- First impression. Your README is one of the first points of contact with a potential user. If you come across as convincing, clear, and reassuring it could be the factor that makes a user try your Actor. +- Extended instructions. The README explains specific and complex input settings. For example, special formatting of the input, any coding-related, or extended functions. +- Support. Your users come back to the README when they face issues. Include links to the tutorials, describe common troubleshooting techniques, share tricks, or warn about bugs. + +## Create a README file + +Every [Actor template](https://apify.com/templates) ships with a +`README.md` file that includes instructions on setting up the project locally. Once you're ready to [publish your Actor](/actors/publishing/publish), edit the file and replace the default content with information aimed at potential users. + +The file's content renders identically on [Apify Store](https://apify.com/store) and on the Actor's page in [Apify Console](https://console.apify.com). + +## Sections to include + +Try to include the following sections in your README and aim for at least 300 words. + +To make the text more readable, try to break it up into smaller chunks. For example, you can use emojis as bullet points. + +### Introduction + +Introduce your Actor and its purpose: + +- Explain in two or three sentences what the Actor does and the easiest way to try it. Mention the goals that the tool helps the user achieve. Describe the input. To grab user's attention, highlight the most important words in bold. +- List the Actor's main features and platform advantages. +- If it's a bundle, mention the steps that the Actor takes, and the obstacles it can overcome. Say upfront how many results users can get for free. + +:::tip Remember the Apify platform + +Your Actor and the Apify platform come as a package. In the README, mention all the advantages that the platform gives to your solution, such as monitoring, access to API, scheduling, possibility of integrations, or proxy rotation. + +::: + +Example headings to use for this section: + +- What is [Actor]? +- What can this [Actor] do? +- What data can [Actor] extract? +- What data can you extract from [target website]? + +### Tutorial + +Create step-by-step instructions on how to use the Actor or include a link to a tutorial on a blog. + +An ordered list is reassuring for the user, and it can be optimized for Google. + +### Pricing + +Don't rely only on the **Pricing** tab on your Actor's detail page to inform users about the costs of using the Actor. Include a section on pricing in your README as well: + +- Inform and reassure the user about the pricing, explain the details. +- If it's a pay per usage Actor, set expectations and explain what it means to pay for compute units. Make it easy for users to imagine how much they will pay for a given dataset. It helps them compare your solution with others. +- If it's price per result, explain how many results a user can get on a free plan and paid plans. +- If it's a bundle that consists of a couple of Actors that are priced differently, explain the difference between all the Actors involved and how that affects the final price of a run. + +Cost-related questions can show up in Google results if they are SEO optimized. It can bring you more traffic and potential users. + +Example headings to use for this section: + +- How much will it cost to scrape [target site]? +- How much will scraping [target site] cost? +- Is scraping [target site] free? +- How much does it cost to extract [target site] data? + +### Input and output examples + +Explain how difficult the input is, what it looks like, and what kind of information users can expect: + +- For the input example, you can include a screenshot of the input schema. This is also a way for people to see the platform even before they create an account. + +- For the output example, use a screenshot if your output schema looks like something you want to promote to users. You can also include a JSON example containing a few objects. Try to keep the continuity between the input example and output example. + +If your datasets come out too complex and require scrolling, you can also show multiple output examples: one for reviews, one for contact details, one for ads, and so on. + +### Actor recommendations + +Use the README to promote your other Actors. + +Apify's system for Actor recommendation works within the same category or similar name. It won't recommend a completely different Actor from the same creator. Make sure to interconnect your work by taking the initiative yourself. You can mention your other Actors in a list or as a table. + +### FAQ and support + +Include an FAQ (Frequently Asked Questions) section to answer potential questions that users might have. Such questions might include: + +- Disclaimers and legality. +- Comparison table between your Actor and similar solutions. +- Tips on how best to use the Actor. +- Troubleshooting and known bugs. +- Interlinking. +- Possibilities of transferring data using an API. +- Integration possibilities. +- Use cases for the Actor and success stories. + +You can also use this section to mention that you're open to creating a custom solution based on the current one and showing a way to contact you. + +## Formatting + +To format your README, use [Markdown](https://www.markdownguide.org/cheat-sheet/) and basic HTML. CSS isn't supported. + +The most important elements are H2 and H3 headings, links to pages, links to images, and tables. + +## Tone + +The README should reflect the level of skill of the target audience for the Actor. It helps people that land on your Actor detail page to set their expectations right away: + +- If your tool's input includes glob patterns or looking for selectors, don't simplify this information. It might be misleading to the user. You will attract the wrong audience, and they will end up churning. +- If your target audience is less technical, use simple terms and avoid code blocks or complex information at the beginning. + +## Length + +There are no strict rules around the length of the README: + +- For someone deciding whether to try your Actor, the first few sections are the most important. They should make it immediately obvious what the tool is about, how hard it is to use, and who it is created for. +- For someone who already uses your Actor, a longer and detailed README is more useful. People treat it as a backup when they need more guidance or when something goes wrong. + +## Images + +To include screenshots and gifs in your README: + +- Use a hosting service. Your own GitHub repository works best for that purpose, because you have full control over it. +- Use SEO-friendly names for the files. +- Keep the files compressed but with good quality. Prevent loading an image or gif for too long. + +Consider making images clickable. You can lead such clicks towards a signup page, which is possible with Markdown. + +If your images are too big or occupy too much space, make them smaller with HTML. + +:::tip Try Carbon for code + +To add code screenshots to your README, try [Carbon](https://github.com/carbon-app/carbon). + +::: + +## Input schema + +The README should serve as a fallback for your users if something in the input schema is unclear. To provide more details about things like input, formatting, or expectations, put it in the README and refer to it from the relevant place in the input schema. + +See also [How to create a great input schema](/academy/actor-marketing-playbook/product-optimization/how-to-create-a-great-input-schema). + +## Optimize for SEO + +According to Google, the README is a landing page that contains the most important information about your Actor. + +A good README must strike a balance between what you want the visitors to know, your users to turn to when they run into trouble, and Google to register when it's indexing pages and considering which one deserves to be placed higher. + +Any part of your README can make it onto Google pages. The intro sentence describing what your Actor is about, a video, a random question. That's why it's important to structure and write your README with SEO in mind. + +### Table of contents + +The H1 heading of your page is the Actor name, so use only H2 and H3 in your README. + +H2 headings form the table of contents. To keep it less crowded, keep the H2s to the basics and push the longer phrases and questions to H3s. + +H3 headings stay hidden in the table of contents until you hover your cursor over it. + +H4 headings don't appear in the table of contents. + +### Keywords + +Do SEO research for keywords and see how they can fit into the text of your README. Prioritize H2s and H3s, add keyword-heavy paragraphs. + +The easiest sections to include keywords in are, for example: + +- API, as in Instagram API +- data, as in extract Instagram data +- Python, as in extract data in Python +- scrape, as in how to scrape X + +It's worth optimizing the headings, since the H2s and H3s are sometimes returned in Google search results. For example, they might appear in the **People also ask** section or get highlighted in the sitelinks of Google search results. + +### Videos + +If your page includes a video, it has a better chance of ranking higher in Google. + +To embed a YouTube video, include its URL. The thumbnail renders automatically as an embedded video player. diff --git a/sources/platform/actors/publishing/publish/index.mdx b/sources/platform/actors/publishing/publish/index.mdx new file mode 100644 index 0000000000..55fb8fcd43 --- /dev/null +++ b/sources/platform/actors/publishing/publish/index.mdx @@ -0,0 +1,60 @@ +--- +title: Publish your Actor +description: Prepare your Actor for publication on Apify Store. +slug: /actors/publishing/publish +sidebar_position: 1 +--- + +By publishing your Actor, you make it available to the public on [Apify Store](https://apify.com/store). Publishing turns your Actor into a product with its own dedicated page, where users can read its documentation, run it, and review it. + +## Before you start + +Before you publish your Actor, update its README file. The README becomes your Actor's public detail page on Apify Store. It's where users can learn about your Actor and how to use it. + +For details, see [Create an Actor README](/actors/publishing/actor-readme). + +## Make your Actor public + +To make your Actor available on Apify Store: + +1. Log in to [Apify Console](https://console.apify.com). +1. In the left-side panel, go to **Development** > **My Actors**. +1. From the table, select the Actor you want to publish. +1. Go to the **Publication** tab. + +Complete all required fields in the following sections: + +1. In the **Display information** section, add an Actor logo and [description](/academy/actor-marketing-playbook/actor-basics/actor-description). +1. In the **Monetization** section, [set up monetization](/actors/publishing/monetize) for your Actor. +1. In the **Sample output** section, add a sample output for your Actor. If the [input schema](/actors/development/actor-definition/input-schema) already includes the sample output, it's added automatically. +1. In the **Output schema** section, define the [output schema](/actors/development/actor-definition/output-schema) of your Actor. Optionally, define also the following schemas: + - [Dataset schema](/storage/dataset-schema) + - [Key-value store schema](/storage/key-value-store-schema) + - [Live-view web server OpenAPI schema](/actors/development/actor-definition/web-server-schema) +1. In **Actor permissions**, define the [permission level](/actors/development/permissions) that your Actor requires. + +Once all sections are marked as completed, select **Publish on Store**. + +## Verify the publication + +To verify that your Actor has been published: + +1. Go to the [Apify Store](https://apify.com/store). +1. Search for your Actor's name. +1. Select your Actor's card and review its dedicated page. + +## Publish Actor's source code + +By default, the source code of your Actor is hidden from the public. + +By making the source files and non-secret [environment variables](/actors/development/programming-interface/environment-variables) of your Actor publicly visible, you make your Actor open source and eligible for payouts through the [Apify Open Source Fair Share program](https://apify.com/partners/open-source-fair-share). + +To publish your Actor's source code: + +1. Log in to [Apify Console](https://console.apify.com). +1. In the left-side panel, go to **Development** > **My Actors**. +1. From the table, select the Actor whose source code you want to publish. +1. Go to the **Publication** tab. +1. In **Display information**, uncheck **Hide source files from Actor detail**. + +You can't publish the source code of an Actor that you build from a private repository. Secret environment variables are never exposed. diff --git a/sources/platform/actors/publishing/quality_score.mdx b/sources/platform/actors/publishing/quality_score.mdx index 876097e0a0..c18453bb34 100644 --- a/sources/platform/actors/publishing/quality_score.mdx +++ b/sources/platform/actors/publishing/quality_score.mdx @@ -67,7 +67,7 @@ Users who have run your Actor multiple times are invited to provide reviews and ### Ease of use -Ease of use evaluates how quickly users can understand and successfully run your Actor. Provide clear, concise titles and descriptions that accurately convey your Actor's functionality. Input field descriptions should be self-explanatory and guide users toward correct usage. A [well-structured README](https://docs.apify.com/academy/actor-marketing-playbook/actor-basics/how-to-create-an-actor-readme) is equally important, particularly for Actors with complex use cases or configuration options. Strong ease of use facilitates user onboarding and improves retention rates. +Ease of use evaluates how quickly users can understand and successfully run your Actor. Provide clear, concise titles and descriptions that accurately convey your Actor's functionality. Input field descriptions should be self-explanatory and guide users toward correct usage. A [well-structured README](/actors/publishing/actor-readme) is equally important, particularly for Actors with complex use cases or configuration options. Strong ease of use facilitates user onboarding and improves retention rates. ### Pricing transparency