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 Apify sense?

In Apify, when we talk about the readme, we don’t mean a guide mainly aimed at developers that explains what the 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 the one described on GitHub:

README files typically include information on:

We mean all of this and even more. In Apify, when we talk about readme, we refer to the public Actor detail page in Store. Specifically, its first tab. The readme exists in the same form both on the web and in Console. So what is it for?

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 but a single word in the README; perhaps with one line word or phrase for symbolism sake. But you'd be missing out if you did that.

Your Actor’s readme has at least 4 functions:

  1. SEO. If your readme is well structured and includes important keywords — both in headings and across the text — it has high chances 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. ****The way your readme is worded and the way you come across is convincing, clear and reassuring can be the factor that will sway the potential user's opinion to try your Actor for their task.
  3. Extended instruction. 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 the blogpost 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, warn about bugs.

README elements theory