Skip to main content

Guidelines for writing tutorials

Create a guide for your users so they can get the best out of your Actor. Make sure your tutorial is both user- and SEO-friendly. Your tutorial will be published on Apify Blog.

These guidelines are of course not set in stone. They are here to give you a general direction of tried-and-tested ways of creating an Actor tutorial.

  1. Use markdown formatting. It might seem like a no-brainer, but it's worth mentioning. Using markdown ensures a smooth transition of your content into our CMS.

  2. Use this structure (also see the tutorial template):

    1. Introduce your tool → What is this X tool for?
    2. Highlight its unique features → What data can I scrape with X tool?
    3. Provide a step-by-step guide, complete with input and output examples → How to use X tool for scraping X website. Step 1… Step 5.
    4. Discuss potential use cases → What are the most frequent use cases of X tool?
    5. Include a call-to-action (CTA) → Try this X tool
    6. Address frequently asked questions (FAQs)
    tip

    Feel free to expand beyond this core structure. For inspiration, check out these tutorials:

  3. Use SEO tools for keyword research. Even the best tutorial won't make an impact if it's hidden in the depths of the internet. Use tools like Answer the Public to find high-volume, high-cost-per-click keywords related to your topic.

  4. Incorporate relevant links. While you're writing, look for opportunities to link to other blog posts on the Apify blog that fit well with your topic. Search engines seem to prefer articles that don’t stand alone.

  5. ChatGPT is your friend, but edit wisely. Feel free to use ChatGPT for generating content, but remember to edit the output. While it's a good tool to get started, it's not perfect and may occasionally make errors.

  6. Additional resources for external writers. For more details on our tone of voice, image specifications, and other guidelines, visit Write for Apify.

  7. After you're done writing, send your tutorial over to one of our writers. They'll take care of it and let you know when it's published.

  8. Once your tutorial is published, don't forget to add a link to it to the Actor's README. That way, your tutorial will get its first backlink! It can also be useful for the users skimming through the README in search for detailed instructions.

Tutorial template​

A simple tutorial template for you to start from. Feel free to expand and modify it as you see fit.

# How to [perform task] automatically

A simple step-by-step guide to [describe what the guide helps achieve].

The web is a vast and dynamic space, continuously expanding and evolving. Often, there's a need to [describe the problem or need the tool addresses]. A handy tool for anyone who wants to [describe what the tool helps with] would be invaluable.

[Actor Name], a tool created to [describe what the tool does]. But before we learn how to set it up, let's explore its capabilities.

## What is [Actor name] for?

[Describe what sets this tool apart and its key features]

So, on the one hand, [describe one set of features or benefits]. On the other hand, [describe another set of features or benefits]. Let's see how you can [perform the task the tool is designed for].

## What data can I get using [Actor name]?

[List specific data that this scraping tool can get]

## How to use [Actor name]

Here's how to [quick intro to the tutorial itself]

### Step 1. Find the [Actor name]

Navigate to [Tool Name] and click the [CTA button]. You'll be redirected to Apify Console. 

### Step 2. Add URL or choose [setting 1], [setting 2], and [setting 3]

[Describe what the user needs to specify or choose]

### Step 3. Hit the Start button

Once you've set everything up, click the Start button. [Describe what happens next]

### Step 4. Check out your output

[Describe how to access and use the output]

### Step 5. Download your data

[Describe how to download data from Console]

## What are the most frequent use cases of [Tool Name]?

[Describe common scenarios where the tool can be useful]

## FAQs

### Are there any limitations?

[Describe any limitations]

### Can I integrate this tool into my existing project or with other tools?

[Describe integration possibilities]

### Can I use this tool to [perform additional tasks]?

[Describe any additional functionalities]

Next up​

Now that your Actor has a name, a README and you have an idea of making a tutorial for it, let's make sure it's visible to Google and the world. In the next lesson we will explore some SEO basics and a few tricks.