docs: rewrite SEO and promotion document

new structure
added details & summary tags for examples
added admonitions
rewrites for clarity & conciseness

Author: TC-MO

sources/academy/platform/get_most_of_actors/seo_and_promotion.md

@@ -5,121 +5,105 @@ sidebar_position: 4
 slug: /get-most-of-actors/seo-and-promotion
 ---
 
-# SEO and promotion
-
 **Optimize your Actors to get more relevant visits from search engines like Google. Set search engine-friendly parameters and share your Actor with the world.**
 
 ---
 
-Work on your Actors does not end when you publish it. Now, it's time to promote your creation and get it to its intended audience. The Apify domain will boost your position with search engines but it won't do all the work. Focus on crafting content according to topics and phrases people search for to give your Actor that extra boost.
-
-**The golden rule of SEO:** Create quality content that provides value and engagement to your users. [Don't over-optimize SEO](https://seo-hacker.com/over-optimization-penalty/) or you risk being penalized by Google.
-
-Think of it this way: your content, URLs, keywords, titles, links, etc. determine the kind of search queries your page is shown in. The quality of the content determines how high it ranks in those results.
-
-For example, if you over-optimize your URLs and title to rank higher in results for high-volume queries, but most people who visit your page immediately leave, Google notices, penalizes you, and your pages sink in the results.
-
-On the other hand, if you precisely address a niche segment of users who will benefit from your Actor and people who open it use your Actor, then Google will love it and push it up in results. Read more about the basics of [content marketing](https://techcrunch.com/2019/04/13/how-do-startups-actually-get-their-content-marketing-to-work/).
-
-## Keywords
-
-Several freemium tools exist that help with identifying the right phrases and keywords:
-
-- [wordstream.com/keywords](https://www.wordstream.com/keywords)
-- [neilpatel.com/ubersuggest](https://neilpatel.com/ubersuggest/)
-- [keywordtool.io](https://keywordtool.io/)
+## Overview
 
-Enter the desired phrase or topic (e.g. Facebook scraper, Web scraping, Facebook API...) and set the **language** to **English**. Ideally, set the **location** to **United States**. After submitting the form, you will see a list of relevant phrases for your query with information about **search** volume** (how many people are searching for this) and **competition** (number of results).
+Work on your Actors does not end when you publish it. Now it's the time to promote your creation and get it to its intended audience. The Apify domain will boost your position with search engines but it won't do all the work. Focus on craftin content according to topics and phrases people search for to give your Actor that extra boost.
 
-The best combinations are those with **high search volume** and **low competition**. Try to find keywords (or topics) relevant to your Actor based on these criteria.
+### SEO fundamentals
 
-**Use your selected keywords on all the important parts of your Actor's page/content**.
+Create quality content that provides value and engagement to your users. Search engines evaluate not just keywords, but how users interact with your content. When your content precisely  addresses a specific user needs and visitors actively engage, search engines will naturally boost your rankings. However, over-optimization can lead to penalties, especially if visitors quickjy leave your page.
 
-- Page title.
-- Meta description.
-- Headings (1st and 2nd-level, ideally).
-- Page body (e.g., README).
-- The texts in your links.
+### Keyword strategy
 
-> While crafting your content with keywords, beware of [over-optimizing or keyword stuffing](https://yoast.com/over-optimized-website/) the page. You can use synonyms or related keywords to help this. Google is smart enough to evaluate the page based on how well the whole topic is covered (not only by keywords), but using them helps.
+Start your keyword research using tools like:
 
-## Optimizing your Actor details
+- [Wordstream](https://www.wordstream.com/keywords)
+- [Ubersuggest](https://neilpatel.com/ubersuggest/)
+- [Keyword tool](https://keywordtool.io/)
 
-While blog posts and promotion are important, your Actor is the main product. Here's how you can make it more SEO-friendly.
+Target English language searches with a focus on US market. The ideal keywords combine high search volume with manageable competition levels. Incorporate these naturally throughout your content, particularly in titles, description, and body text.
 
-### Name
+:::warning Keyword stuffing
 
-The Actor name is your Actor's developer-style name, which is prefixed by your username (e.g. `jancurn/find-broken-links`). The name is used to generate URL used for your Actor (e.g. https://apify.com/jancurn/find-broken-links), making it an important signal for search engines. The name should also be readable and clear enough, so that people using your Actor can understand what it does.
+While crafting your content with keywords, beware of [over-optimizing or keyword stuffing](https://yoast.com/over-optimized-website/) the page. You can use synonyms or related keywords to help this. Google is smart enough to evaluate the page based on how well the whole topic is covered (not only by keywords), but using them helps.
 
-[Read more about naming your Actor](./naming_your_actor.md)!.
+:::
 
-### Title
+### Actor optimization
 
-The Actor title provides a human-readable name. The title is the most important real estate from an SEO standpoint. It should exactly match the most likely search query that potential users of your Actor will use.
+While blog posts and promotion are important, your Actor is the main product
 
-At the same time, it should give your Actor a clear name for people who will use it every day. If you’re working on an "Amazon crawler" or a "Google Places API", use the following formats for your Actor's name:
+#### Name
 
-> **GOOD**: Crawler for Amazon, API for Google Places, Search in Kickstarter.
-> <br/> **BETTER**: Amazon crawler, Google Places API, Kickstarter search.
+Your Actor's name should be developer-friendly and clearly indicate functionality, such as `username/descriptive-function-name`.
 
-### Description
+#### Title
 
-Your Actor's description should contain a concise but accurate description of what your Actor does, targeted at people who are deciding whether to use it or not. Get straight to the point and avoid any boilerplate text.
+The title is the most important real estate from an SEO standpoint.
+You should aim to create titles that balance searchability with clarity.
 
-> **GOOD**: Crawls Amazon.com and extracts ... <br/> **AVOID**: This Actor crawls Amazon.com in order to extract ...
+<details>
+    <summary>Actor title - examples</summary>
 
-The description is used by search engines to understand what the Actor is about, so it should contain some of the most popular variations and derivations of the [title](#title), including things people might search for.
+**GOOD**: Crawler for Amazon, API for Google Places, Search in Kickstarter.
+<br/> **BETTER**: Amazon crawler, Google Places API, Kickstarter search.
 
-> **GOOD**: This Amazon bot will help, whereas the Amazon API won’t. Use the crawler...
-> <br/> **AVOID**: This crawler will search through results in Amazon and offers you...
+</details>
 
-If you’re not sure about similar phrases, check out the Google suggest tool in the search, and it will show you some hints and tips. Of course, the description should primarily be about what the Actor does, but it’s always a good idea to enrich the text with popular keywords.
+#### Description
 
-![Google suggestions example](./images/actors-publishing-google.png)
+The description is used by search engines to understand what the Actor is about.
+You should aim to write descriptions that immediately communicate your Actor's purpose without unnecessary introductory phrases.
 
-### README
+<details>
+    <summary>Actor description - examples</summary>
 
-The README․md file represents a complete description of your Actor, intended for its users. If your Actor's users are technical folks, you can be technical in the README. If they aren't, keep it simple. [See our article on writing great READMEs](https://help.apify.com/en/articles/2912548-how-to-write-great-readme-for-your-actors).
+**GOOD**: Crawls Amazon.com and extracts ... <br/>
+**AVOID**: This Actor crawls Amazon.com in order to extract ...
+**GOOD**: This Amazon bot will help, whereas the Amazon API won’t. Use the crawler...<br/>
+**AVOID**: This crawler will search through results in Amazon and offers you...
+</details>
 
-You have lots of room for SEO optimization in the README, without compromising readability for your users. Make sure the text includes other variants of what potential users of your Actor might search for. A good place for these is in the captions and headlines but keywords in the body text will also help. It’s also a good idea to repeat the name of the Actor several times.
+#### README
 
-> **GOOD**: You can use this Amazon Crawler with your code (Python, PHP, Java) to crawl Amazon without the API...
-> <br/> **AVOID**: Follow the instructions in the Readme and if you have any comments, see the FAQ section...
+Your readme file should serve as a comprehensive guide matching your audience's technical expertise. Include relevant keywords naturally within the content, and incorporate meaningful internal and external links. When refernecing external resources, ensure the links provide value while supporting your SEO strategy.
 
-An important part of SEO is internal and external linking. Don’t be shy - add links to your README leading to similar [Actors](https://apify.com/store) or any interesting article in [Apify Help](https://help.apify.com/) that could assist your users. If your Actor is scraping a certain website, make sure to add a link to that website. If the Actor uses any external libraries, make sure to link their pages.
+<details>
+    <summary>Actor README - examples</summary>
 
-If you’ve created other Actors, it’s completely fine to pop in a promo for them at the end. It’s even better if you edit your old Actors and put in a link to your new Actor. We’ll take care of extra promotion on the [Apify homepage](https://apify.com/) or [Apify Store](https://apify.com/store) - especially if you’ve done a great job of describing your Actors!
+**GOOD**: You can use this Amazon Crawler with your code (Python, PHP, Java) to crawl Amazon without the API...<br/>
+**AVOID**: Follow the instructions in the Readme and if you have any comments, see the FAQ section...<br />
 
-> **GOOD**: Like my <a href="#">Amazon Crawler</a>? See my <a href="#">Amazon Review Crawler</a>.
-> <br/> **AVOID**: Check out my Amazon Crawler.
 
-## Promotion
+**GOOD**: Like my <a href="#">Amazon Crawler</a>? See my <a href="#">Amazon Review Crawler</a>.<br/>
+**AVOID**: Check out my Amazon Crawler.
 
-Now that you’ve created a cool new Actor, let others see it! Share it on your personal Twitter, Facebook, Reddit or any other social platform. Always provide a link with the Actor's name. Use #hashtags on Twitter to catch attention. Provide a small “why is this good” segment when sharing inside any group discussions. We will promote your Actor sooner or later, but more links mean more attention from Google from the beginning.
+</details>
 
-### External promotion
+### Promotion strategy
 
-- Try to publish an article about your Actor in relevant external magazines like [hackernoon.com](https://hackernoon.com/) or [techcrunch.com](https://techcrunch.com/). Do not limit yourself to blogging platforms.
-- If you publish an article in external media (magazine, blog etc.), be sure to include backlinks to your Actor and the Apify website to strengthen the domain's SEO.
-- It's always better to use backlinks with the [`dofollow` attribute](https://raventools.com/marketing-glossary/dofollow-link/).
-- Always use the most relevant URL as the backlink's landing page. For example, when talking about Apify Store, link to the Store page ([apify.com/store](https://apify.com/store)), not to Apify homepage ([apify.com](https://apify.com)).
-- Always use the most relevant keyword or phrase for the backlink's text. This can boost the landing page's SEO and help the readers know what to expect from the link.
+Share your Actor through multiple channels while maintaining authenticity.
 
-> **GOOD**: Try the [Facebook scraper](https://apify.com/apify/facebook-pages-scraper) now.
-> <br/> **AVOID**: Try the Facebook scraper [here](https://apify.com/apify/facebook-pages-scraper).
+#### External promotion
 
-### Social media and forums
+- Publish articles on platforms like [hackernoon.com](https://hackernoon.com/) or [techcrunch.com](https://techcrunch.com/).
+- Include backlinks with [`dofollow`](https://raventools.com/marketing-glossary/dofollow-link/) attribute.
+- Use relevant landing page URL
+  - For example when talking about Apify Store, link to the [Store page](https://apify.com/store), not the [Apify homepage](https://apify.com/)
+- Create descriptive anchor text
 
-- Use relevant and widely used hashtags (Twitter).
+#### Social media promotion
 
-> **GOOD**: Need to crawl #Amazon or #Yelp? See my Amazon crawler `https://`...
-> <br/> **AVOID**: I just #created something, check it out on Apify...
+- Use meaningful hashtags on Twitter
+- Engage in relevant group discussions
+- Participate in technical communities authentically
+- Focus on solving problems while naturally introducing your Actor
 
-- Post in groups or pages with relevant target groups (Facebook and LinkedIn).
-- Always use the most relevant URL as the backlink's landing page.
-- Use other relevant websites for promotion. For example, [news.ycombinator.com](https://news.ycombinator.com/), [producthunt.com](https://www.producthunt.com/), [indiehackers.com](https://www.indiehackers.com/), and [dev.to](https://dev.to/)
-- While promoting the Actor on forums like Reddit or Quora, try not to post strictly promotional answers. If you help someone with their problem, all readers will be more willing to upvote your posts or check the Actor.
-- If it's possible to upvote your posts, do it and get others to help you.
+Remember to maintain a helpful presence in communities, solving problems while appropriately refencing your Actor as a solution when relevant.
 
 ## Next up {#next}