Merge pull request #457 from apify/academy-content-migration-publishing-actors

academy/content-migration

Author: mstephen19

content/academy/apify_platform/publishing_actors_on_apify_store/actor_readme.md

@@ -0,0 +1,84 @@
+---
+title: Actor README
+description: Learn how to write a comprehensive README to help users better navigate, understand and run the actor.
+menuWeight: 2
+paths:
+    - apify-platform/publishing-actors-on-apify-store/actor-readme
+---
+
+## What is the point of this guide?
+
+- It should also be a "template" for developers developing new public actors so that they have a structure and guidance for writing the readmes.
+- The goal is to ensure that more people will understand and run their actors.
+- Whenever you build an actor, think of the original request/idea and the "use case" = "user need" it should solve, please take notes and share them with Apify, so we can help you write a blog post supporting your actor with more information, more detailed explanation, better SEO.
+- Consider adding a video, images, and screenshots to your readme to break up the text.
+- This is an example of an actor with a readme that corresponds well to the guidelines below:
+  - [https://apify.com/dtrungtin/airbnb-scraper](https://apify.com/dtrungtin/airbnb-scraper)
+- Tip no.1: if you want to add snippets of code anywhere in your readme, you can use [Carbon](https://github.com/carbon-app/carbon).
+- Tip no.2: if you need any quick Markdown guidance, check out [https://www.markdownguide.org/cheat-sheet/](https://www.markdownguide.org/cheat-sheet/)
+
+## What should you add to your actor readme?
+
+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.
+
+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, or a business use case, or a blog post.
+
+3. **How much will it cost to scrape (target site)?**
+
+    - Simple text explaining what type of proxies are needed and how many platform credits (calculated mainly from consumption units) are needed for 1000 results.
+    - This is calculated from carrying out several runs (or from runs saved in the DB). @Zuzka can help if needed. [Information in this table](https://docs.google.com/spreadsheets/d/1NOkob1eYqTsRPTVQdltYiLUsIipvSFXswRcWQPtCW9M/edit#gid=1761542436), tab "cost of usage".
+    - Here’s an example for this section:
+
+    > ## How much will it cost me to scrape Google Maps reviews?
+    >
+    > <br/> Apify provides you with $5 free usage credits to use every month on the Apify Free plan and you can get up to 100,000 reviews from this Google Maps Reviews Scraper for those credits. So 100k results will be completely free!
+    > <br/> But if you need to get more data or to get your data regularly you should grab an Apify subscription. We recommend our $49/month Personal plan - you can get up to 1 million Google Maps reviews every month with the $49 monthly plan! Or 10 million with the $499 Team plan - wow!
+
+4. **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.
+    - 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.
+
+    ![How to scrape a website - numbered tutorial]({{@asset apify_platform/publishing_actors_on_apify_store/images/how-to-scrape-target-site.webp}})
+
+5. **Is it legal to scrape (target site)?**
+
+    - This can be used as boilerplate text for the legal section, but you should use your own judgement 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](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation) 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](https://blog.apify.com/is-web-scraping-legal/)
+
+6. **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](https://apify.com/vdrmota/twitter-scraper/input-schema) for more information.
+
+7. **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/drobnikj/crawler-google-places#output-example](https://apify.com/drobnikj/crawler-google-places#output-example)
+
+8. **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 GitHub readmes that stand 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.
+
+[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)
+
+## [](#next) Next up
+
+If you followed all the tips described above, your actor README should be good to go! In the [next lesson]({{@link apify_platform/publishing_actors_on_apify_store/seo_and_promotion.md}})! we will dive deeper into how you can improve your README's SEO and promote your actor to ensure it reaches as many potential users as possible!

content/docs/actors/images/actors-publishing-google.png renamed to content/academy/apify_platform/publishing_actors_on_apify_store/images/actors-publishing-google.png

@@ -1,9 +1,9 @@
 ---
 title: Monetizing your actor
 description: Learn how you can use Apify to monetize your web scraping and automation projects.
-menuWeight: 2
+menuWeight: 3
 paths:
-  - apify-platform/publishing-actors-on-apify-store/monetizing-your-actor
+    - apify-platform/publishing-actors-on-apify-store/monetizing-your-actor
 ---
 
 # [](#monetizing-your-actor) Monetizing your actor
@@ -22,7 +22,6 @@ First, go to your actor page, **Actors → My Actors** and click on the actor yo
 
 Our support team will be notified about your request and promptly contact you to discuss the desired price and trial length for your actor, and help you fill in your billing details.
 
-
 ## [](#price-and-trial-length) Price and trial length
 
 **You choose the price and free trial length of your actor.** Apify can give you advice about the best practices of the most successful actors, but at the end of the day, we give developers full control over the pricing strategy of their tools.

content/docs/actors/images/actors-publishing-google.webp renamed to content/academy/apify_platform/publishing_actors_on_apify_store/images/actors-publishing-google.webp

@@ -1,10 +1,12 @@
 ---
 title: Naming your actor
 description: Apify's standards for actor naming. Learn how to choose the right name for scraping and non-scraping actors and how to optimize your actor for search engines.
+menuWeight: 1
 paths:
-# NOTE: IF ADDING A NEW PATH, LEAVE THE OLD ONES FOR REDIRECTS
+    # NOTE: IF ADDING A NEW PATH, LEAVE THE OLD ONES FOR REDIRECTS
     - actor/publishing/naming-your-actor
     - actors/publishing/naming-your-actor
+    - apify-platform/publishing-actors-on-apify-store/naming-your-actor
 ---
 
 # [](#naming-your-actor) Naming your actor
@@ -19,24 +21,23 @@ For actors such as [YouTube Scraper](https://apify.com/bernardo/youtube-scraper)
 
 GOOD:
 
-* Technical name (actor's name in the [Apify Console](https://console.apify.com)): **${domain}-scraper**, e.g. **youtube-scraper**.
-* Publication title for the Apify Store: **${Domain} Scraper**, e.g. **YouTube Scraper**.
-* Name of the GitHub repository: **actor-${domain}-scraper**, e.g. **actor-youtube-scraper**.
+- Technical name (actor's name in the [Apify Console](https://console.apify.com)): **${domain}-scraper**, e.g. **youtube-scraper**.
+- Publication title for the Apify Store: **${Domain} Scraper**, e.g. **YouTube Scraper**.
+- Name of the GitHub repository: **actor-${domain}-scraper**, e.g. **actor-youtube-scraper**.
 
 AVOID:
 
-* Technical name: **the-scraper-of-${domain}**, e.g. **the-scraper-of-youtube**.
-* Publication title: **The Scraper of ${Domain}**, e.g. **The Scraper of YouTube**.
-* GitHub repository: **actor-the-scraper-of-${domain}**, e.g. **actor-the-scraper-of-youtube**.
+- Technical name: **the-scraper-of-${domain}**, e.g. **the-scraper-of-youtube**.
+- Publication title: **The Scraper of ${Domain}**, e.g. **The Scraper of YouTube**.
+- GitHub repository: **actor-the-scraper-of-${domain}**, e.g. **actor-the-scraper-of-youtube**.
 
 If your actor only caters to a specific service on a domain (and you don't plan on extending it), add the service to the actor's name.
 
 For example,
 
-* Technical name: **${domain}-${service}-scraper**, e.g. **google-search-scraper**.
-* Publication title: **${Domain} ${Service} Scraper**, e.g. [**Google Search Scraper**](https://apify.com/apify/google-search-scraper).
-* GitHub repository: **actor-${domain}-${service}-scraper**, e.g. **actor-google-search-scraper**.
-
+- Technical name: **${domain}-${service}-scraper**, e.g. **google-search-scraper**.
+- Publication title: **${Domain} ${Service} Scraper**, e.g. [**Google Search Scraper**](https://apify.com/apify/google-search-scraper).
+- GitHub repository: **actor-${domain}-${service}-scraper**, e.g. **actor-google-search-scraper**.
 
 ## [](#non-scraping-actors) Non-scraping actors
 
@@ -48,18 +49,22 @@ Below are examples for the [Google Sheets](https://apify.com/lukaskrivka/google-
 
 GOOD:
 
-* Technical name: **google-sheets**.
-* Publication title: **Google Sheets Import & Export**.
-* GitHub repository: **actor-google-sheets**.
+- Technical name: **google-sheets**.
+- Publication title: **Google Sheets Import & Export**.
+- GitHub repository: **actor-google-sheets**.
 
 AVOID:
 
-* Technical name: **import-to-and-export-from-google-sheets**.
-* Publication title: **Actor for Importing to and Exporting from Google Sheets**.
-* GitHub repository: **actor-for-import-and-export-google-sheets**.
+- Technical name: **import-to-and-export-from-google-sheets**.
+- Publication title: **Actor for Importing to and Exporting from Google Sheets**.
+- GitHub repository: **actor-for-import-and-export-google-sheets**.
 
 ## [](#renaming-your-actor) Renaming your actor
 
 **Warning!** Changing your actor's **technical name** may break current integrations for that actor's users. This is why some actors in the Apify Store don't have consistent naming. For the same reason, it is best to change the actor's name early, before you build a steady user base.
 
 The **publication title**, however, can be changed without any problems.
+
+## [](#next) Next up
+
+Now that your actor is properly named and you know the differences between your actor's technical name and publication title, it's time to take the [next step]({{@link apify_platform/publishing_actors_on_apify_store/actor_readme.md}})! into making your actor public in Apify Store by ensuring that it has a well-structured and comprehensive README.

content/academy/apify_platform/publishing_actors_on_apify_store/images/how-to-scrape-target-site.webp

@@ -1,23 +1,19 @@
 ---
 title: Publishing your actor
 description: Prepare your actor for the Apify Store with a description and README file and learn how to make your actor available to the public.
-menuWeight: 1
+menuWeight: 4
 paths:
-  - apify-platform/publishing-actors-on-apify-store/publishing-your-actor
+    - apify-platform/publishing-actors-on-apify-store/publishing-your-actor
 ---
 
 # [](#publishing-actor) Publishing your actor
 
-Before you make your actor public, it is important to write a good **Description** and **README** sections, so that users can understand what your actor does, how to configure its inputs, and what kind of output it returns.
+Before you make your actor public, it is important to make sure your actor has good **Description** and **README** sections so that users can understand what your actor does, how to configure its inputs, and what kind of output it returns. In this lesson, we will briefly go over each of the fields you have to fill in before publishing your actor. For more detailed information about [SEO and promotion]({{@link apify_platform/publishing_actors_on_apify_store/seo_and_promotion.md}})! and [how to write a comprehensive README]({{@link apify_platform/publishing_actors_on_apify_store/actor_readme.md}})!, check the previous lessons in this section of the academy.
 
 You can find the Title and description configurations by going to **Apify Console** → **Actors** → **My Actors** → **your-actor** → **Settings → Publication**
 
 ![Actor publication settings]({{@asset apify_platform/publishing_actors_on_apify_store/images/actor-publication-settings.webp}})
 
-Writing a complete and descriptive README can significantly increase your chances of convincing users to give your actors a try. Not only that, but you can also include popular keywords in text to increase the traffic to your actor's page. For more information on how you can **fine-tune your actor’s title, description, and Readme**, check our in-depth [SEO guide](https://docs.apify.com/actors/publishing/seo-and-promotion).
-
-Now, let’s move on to understand exactly how to add a description and README to your Apify actors.
-
 ## [](#description) Description
 
 The actor’s description is a short paragraph describing the actor’s purpose. It will be displayed on the actor’s page right below its title.
@@ -30,15 +26,15 @@ While writing your actor’s description you also have the option to write an SE
 
 ## [](#readme) README
 
-The next step is to write a **README** detailing the actor’s features, reasons to scrape the targeted website, and an explanation about how to use the actor.
+The next step is to include a **README** detailing the actor’s features, reasons to scrape the targeted website, and an explanation about how to use the actor.
 
-Keep in mind that the actor’s README is generated from your README.md file, and you can apply the same [SEO principles](https://docs.apify.com/actors/publishing/seo-and-promotion) throughout the README.
+Keep in mind that the actor’s README is generated from your README.md file, and you can apply the same [SEO principles]({{ apify_platform/publishing_actors_on_apify_store/seo_and_promotion.md}})! described in the previous lesson to your README.
 
-To save some time when writing an actor’s README, we recommend using the template below as a starting point:
+To save some time when writing an actor’s README, you can use the template below as a starting point:
 
 [https://github.com/zpelechova/readme-template](https://github.com/zpelechova/readme-template)
 
-Note that the complexity of the README should match the actor’s complexity. This means that the template above is not immutable and that you can adapt it to fit the particularities of your actor. You can check our guide, **[How to write great README for your actors](https://help.apify.com/en/articles/2912548-how-to-write-great-readme-for-your-actors)**, for more examples of README files.
+Note that the complexity of the README should match the actor’s complexity. This means that the template above is not immutable and that you can adapt it to fit the particularities of your actor.
 
 ## [](#make-your-actor-public) Make your actor Public
 
@@ -78,7 +74,6 @@ Actors that require some sort of authentication will always fail the tests despi
 
 You can easily implement your own tests and customize them to fit your actor's particularities by using our public [Actor Testing](https://apify.com/pocesar/actor-testing) tool available on the Apify store.
 
-
 ## [](#next) Next up
 
 Congratulations! Now, your actor is available to the public in the Apify Store. In the [next lesson]({{@link apify_platform/publishing_actors_on_apify_store/monetizing_your_actor.md}})!, we'll learn how you can monetize your actors to start making money on the Apify platform.