docs: rewrite local development section (#931)

rewrite the local development section for clarity & conciseness
restructure the document with additional headings
add admonitions about:
prequisites
monetization
benefits of local development

---------

Co-authored-by: Jan Bárta <[email protected]>

sources/platform/actors/development/quick_start/start_locally.md

@@ -1,89 +1,131 @@
 ---
 title: Local development
 sidebar_position: 1
-description: Create your first Actor locally on your machine and then deploy it to the Apify platform and run it in the cloud.
+description: Create your first Actor locally on your machine, deploy it to the Apify platform, and run it in the cloud.
 slug: /actors/development/quick-start/locally
 ---
 
-**Create your first Actor locally on your machine and then deploy it to the Apify platform and run it in the cloud.**
+**Create your first Actor locally on your machine, deploy it to the Apify platform, and run it in the cloud.**
 
 ---
 
-> Prerequisite - You need to have [Node.js](https://nodejs.org/en/) version 16 or higher with NPM installed on your computer.
+:::info Prerequisites
 
-## 1. Install Apify CLI
+You need to have [Node.js](https://nodejs.org/en/) version 16 or higher with NPM installed on your computer.
 
-On macOS (or Linux), you can install the Apify CLI via the Homebrew package manager.
+:::
+
+## Install Apify CLI
+
+### MacOS/Linux
+
+You can install the Apify CLI via the [Homebrew package manager](https://brew.sh/).
 
 ```bash
 brew install apify-cli
 ```
 
-Otherwise, use [NPM](https://www.npmjs.com/) to install the Apify CLI.
+### Other platforms
+
+Use [NPM](https://www.npmjs.com/) to install the Apify CLI.
 
 ```bash
 npm -g install apify-cli
 ```
 
-For more installation and advanced usage information, see the [Apify CLI documentation](https://docs.apify.com/cli/).
+Visit [Apify CLI documentation](https://docs.apify.com/cli/) for more information regarding installation and advanced usage.
 
-## 2. Create your Actor
+## Create your Actor
 
-You can use the following command to create an Actor:
+To create a new Actor, use the following command:
 
 ```bash
 apify create
 ```
 
-You will be prompted to name your Actor (e.g, my-actor), and choose the programming language you would like to use (JavaScript, TypeScript, or Python). Next, you will be presented with a list of Actor development templates. After choosing your preferred template the CLI will:
+The CLI will prompt you to:
 
-- Create a `my-actor` directory containing boilerplate code.
-- Install all the project dependencies.
+1. _Name your Actor_: Enter a descriptive name for your actor, such as `your-actor-name`
+1. _Choose a programming language_: Select the language you want to use for your Actor (JavaScript, TypeScript, or Python).
+1. _Select a development template_: Choose a template from the list of available options.
+
+After selecting the template, the CLI will:
+
+- Create a `your-actor-name` directory with the boilerplate code.
+- Install all project dependencies
 
 ![Creation](./images/actor-create.gif)
 
-Finally, switch to your newly created Actor directory:
+Navigate to the newly created Actor directory:
 
 ```bash
-cd my-actor
+cd your-actor-name
 ```
 
-## 3. Explore the source code in your editor
+## Explore the source code in your editor
 
-Next, let's explore the Actor's source code. We will use the "PuppeteerCrawler in JavaScript" template code as an example, but all Actor templates follow a similar organizational pattern. The important parts are:
+After creating your Actor, explore the source code in your preferred code editor, We'll use the `Crawlee + Puppeteer + Chrome` template code as an example, but all Actor templates follow a similar organizational pattern. The important directories and filer are:
 
-- `src` directory and, namely, the `src/main.js` file, which is the actual code of an Actor.
-- `actor` directory containing Actor's definition files such as `actor.json` and `Dockerfile`. These are important once you deploy your code to the Apify platform.
-- `storage` directory containing the local emulation of [Apify Storage](../../../storage), namely [key-value store](../../../storage/key-value-store), [dataset](../../../storage/dataset), and [request queue](../../../storage/request-queue).
+### `src` Directory
 
-![Actor source code](./images/actor-local-code.png)
+- `srx/main.js`: This file contains the actual code of your Actor
 
-> The following chapters will teach you more about an Actor's structure and files.
+### `actor` Directory
 
-## 4. Run it locally
+- `[actor/json](https://docs.apify.com/platform/actors/development/actor-definition/actor-json)`: This file defines the Actor's configuration, such as input and output specifications.
+- `[Dockerfile](https://docs.apify.com/platform/actors/development/actor-definition/dockerfile)`: This file contains instructions for building the Docker image for your Actor.
 
-To run the Actor, call:
+### `storage` Directory
+
+- This directory emulates the [Apify Storage](../../../storage/index.md)
+  - [Dataset](../../../storage/dataset.md)
+  - [Key-Value Store](../../../storage/key_value_store.md)
+  - [Request Queue](../../../storage/request_queue.md)
+
+![Actor source code](./images/actor-local-code.png)
+
+## Run it locally
+
+To run your Actor locally, use the following command:
 
 ```bash
 apify run
 ```
 
-Shortly after that, you will see the log of the Actor. The results will be stored in the local dataset under the `storage/dataset/default` directory.
+After executing this command, you will see the Actor's log output in your terminal. The results of the Actor's execution will be stored in the local dataset located in the `storage/dastasets/default` directory.
 
 ![Actor source code](./images/actor-local-run.png)
 
-## 5. Deploy it to Apify platform
+:::note Local testing & debugging
 
-In order to push your Actor to the Apify platform, you need to first sign in to Apify with the CLI tool:
+Running the Actor locally allows you to test and debug your code before deploying it to the Apify platform.
 
-```bash
-apify login
-```
+:::
 
-And then, you can push your Actor under your Apify account with the following:
+## Deploy it to Apify platform
 
-```bash
-apify push
-```
+Once you are satisfied with your Actor, to deploy it to the Apify platform, follow these steps:
+
+1. _Sign in to Apify with the CLI tool_
+
+    ```bash
+    apify login
+    ```
+
+    This command will prompt you to provide your API token that you can find in Console.
+
+1. _Push your Actor to the Apify platform_
+
+    ```bash
+    apify push
+    ```
+
+    This command will upload your Actor's code and configuration to the Apify platform, where it can be executed and managed.
+
+    :::note Actor monetization
+
+    If you have successfully completed your first Actor, you may consider [sharing it with other users and monetizing it](../../publishing/index.mdx). The Apify platform provides opportunities to publish and monetize your Actors, allowing you to share your work with the community and potentially generate revenue.
+
+    :::
 
-> If you successfully finished your first Actor, you may consider [sharing it with other users and monetizing it](../../publishing/index.mdx).
+By following these steps, you can seamlessly deploy your Actors to the Apify platform, enabling you to leverage its scalability, reliability, and advanced features for your web scraping and data processing projects.