docs: Improve Quick Start section in the platform docs

sources/platform/actors/development/quick_start/index.mdx

@@ -1,53 +1,59 @@
 ---
 title: Quick start
 sidebar_position: 1
-description: Create your first Actor using the Apify Console IDE or locally.
+description: Create your first Actor using the Apify Web IDE or locally in your IDE.
 slug: /actors/development/quick-start
 ---
 
-# Development: Quick start
+import Card from "@site/src/components/Card";
+import CardGrid from "@site/src/components/CardGrid";
 
-**Create your first Actor using the Apify Console IDE or locally.**
+**Create your first Actor using the Apify Web IDE or locally in your IDE.**
 
 ---
 
-:::note
+:::info Before you build
 
 Before you start building your own Actor, try out a couple of existing Actors from [Apify Store](https://apify.com/store). See the [Running Actors](../../running/index.md) section for more information on running existing Actors.
 
 :::
 
-## Language
+## Technology stack
 
 Any code that can run inside of a Docker container can be turned into Apify [Actor](../../index.mdx). This gives you freedom in choosing your technical stack, including programming language and technologies.
 
 But to fully benefit from running on top of the Apify platform, we recommend you choose either JavaScript/Node.js or Python, where Apify provides first-level support regarding its SDK, API clients, and learning materials.
 
-For these languages, you can also choose from many code templates that help you to kickstart your project quickly:
+For these languages, you can also [choose from many code templates](https://apify.com/templates) that help you to kickstart your project quickly.
 
-<a href="https://apify.com/templates" target="_blank">
-    <img src={require("./images/templates.png").default} width="70%" />
-</a>
+![Actor Templates](./images/templates.png)
 
-## [](#local-development)Local development
+## Development Paths
 
-You can create Actor in two ways:
+You can develop Actor in two ways:
 
-- Using the **Web IDE** in [Apify Console](https://console.apify.com). This is the fastest way to kick-start your Actor development and try out the Apify platform.
-- Develop your Actor **locally** and only deploy to the Apify platform when it is production ready. This way, you benefit from your local setup for a better development and debugging experience. After you are done with the development, you can easily [deploy](./deployment) your Actor to Apify platform.
+### Local development
 
-Now, let's start with:
+Develop your Actor locally in your IDE and only deploy to the Apify platform when it is production ready.
 
-import Card from "@site/src/components/Card";
-import CardGrid from "@site/src/components/CardGrid";
+This way, you benefit from your local setup for a better development and debugging experience. After you are done with the development, you can [deploy](./deployment) your Actor to the Apify platform.
 
 <CardGrid>
     <Card
-        title="Apify Console web IDE"
-        to="/platform/actors/development/quick-start/web-ide"
+        title="Start Locally in Your IDE"
+        to="/platform/actors/development/quick-start/locally"
     />
+</CardGrid>
+
+### Web IDE
+
+Using the Web IDE in [Apify Console](https://console.apify.com).
+
+This is the fastest way to kick-start your Actor development and try out the Apify platform.
+
+<CardGrid>
     <Card
-        title="Locally on your machine"
-        to="/platform/actors/development/quick-start/locally"
+        title="Start in Apify Web IDE"
+        to="/platform/actors/development/quick-start/web-ide"
     />
 </CardGrid>

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

@@ -9,123 +9,146 @@ slug: /actors/development/quick-start/locally
 
 ---
 
-:::info Prerequisites
+## What you'll learn
 
-You need to have [Node.js](https://nodejs.org/en/) version 16 or higher with `npm` installed on your computer.
+This guide walks you through the full lifecycle of an Actor. You'll start by creating and running it locally with the Apify CLI, then learn to configure its input and data storage. Finally, you will deploy the Actor to the Apify platform, making it ready to run in the cloud.
 
-:::
+## Prerequisites
 
-## Install Apify CLI
+- [Node.js](https://nodejs.org/en/) version 16 or higher with `npm` installed on your computer.
+- The [Apify CLI](/cli/docs/installation) installed.
+- Optional: To deploy your Actor, [sign in](https://console.apify.com/sign-in).
 
-### MacOS/Linux
+## Step 1: Create your Actor
 
-You can install the Apify CLI via the [Homebrew package manager](https://brew.sh/).
+Use Apify CLI to create a new Actor:
 
 ```bash
-brew install apify-cli
+apify create
 ```
 
-### Other platforms
+The CLI will ask you to:
 
-Use [NPM](https://www.npmjs.com/) to install the Apify CLI.
+1. Name your Actor (e.g., `your-actor-name`)
+2. Choose a programming language (`JavaScript`, `TypeScript`, or `Python`)
+3. Select a development template
+   :::info Explore Actor templates
 
-```bash
-npm -g install apify-cli
-```
+   Browse the [full list of templates](https://apify.com/templates) to find the best fit for your Actor.
 
-Visit [Apify CLI documentation](https://docs.apify.com/cli/) for more information regarding installation and advanced usage.
+   :::
 
-## Create your Actor
+The CLI will:
 
-To create a new Actor, use the following command:
+- Create a `your-actor-name` directory with boilerplate code
+- Install all project dependencies
+
+Now, you can navigate to your new Actor directory:
 
 ```bash
-apify create
+cd your-actor-name
 ```
 
-The CLI will prompt you to:
+## Step 2: Run your Actor
 
-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.
+Run your Actor with:
 
-After selecting the template, the CLI will:
+```bash
+apify run
+```
 
-- Create a `your-actor-name` directory with the boilerplate code.
-- Install all project dependencies
+:::tip Clear data with --purge
 
-![Creation](./images/actor-create.gif)
+During development, use `apify run --purge`. This clears all results from previous runs, so it's as if you're running the Actor for the first time.
 
-Navigate to the newly created Actor directory:
+:::
+
+You'll see output similar to this in your terminal:
 
 ```bash
-cd your-actor-name
+INFO  System info {"apifyVersion":"3.4.3","apifyClientVersion":"2.12.6","crawleeVersion":"3.13.10","osType":"Darwin","nodeVersion":"v22.17.0"}
+Extracted heading { level: 'h1', text: 'Your full‑stack platform for web scraping' }
+Extracted heading { level: 'h3', text: 'TikTok Scraper' }
+Extracted heading { level: 'h3', text: 'Google Maps Scraper' }
+Extracted heading { level: 'h3', text: 'Instagram Scraper' }
 ```
 
-## Explore the source code in your editor
+As you can see in the logs, the Actor extracts text from a web page. The main logic lives in `src/main.js`. Depending on your template, this file may be `src/main.ts` (TypeScript) or `src/main.py` (Python).
 
-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:
+In the next step, we’ll explore the results in more detail.
 
-### `src` Directory
+## Step 3: Explore the Actor
 
-- `src/main.js`: This file contains the actual code of your Actor
+Let's explore the Actor structure.
 
-### `.actor` Directory
+### The `.actor` folder
 
-- [`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.
+The `.actor` folder contains the Actor configuration. The `actor.json` file defines the Actor's name, description, and other settings. Find more info in the [actor.json](https://docs.apify.com/platform/actors/development/actor-definition/actor-json) definition.
 
-### `storage` Directory
+### Actor's `input`
 
-- 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)
+Each Actor accepts an `input object` that tells it what to do. The object uses JSON format and lives in `storage/key_value_stores/default/INPUT.json`.
 
-![Actor source code](./images/actor-local-code.png)
+:::info Edit the schema to change input
 
-## Run it locally
+To change the `INPUT.json`, edit the `input_schema.json` in the `.actor` folder first.
 
-To run your Actor locally, use the following command:
+This JSON Schema validates input automatically (no error handling needed), powers the Actor's user interface, generates API docs, and enables smart integration with tools like Zapier or Make by auto-linking input fields.
 
-```bash
-apify run
-```
+:::
 
-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/datasets/default` directory.
+Find more info in the [Input schema](/platform/actors/development/actor-definition/input-schema) documentation.
 
-![Actor source code](./images/actor-local-run.png)
+### Actor's `storage`
 
-:::note Local testing & debugging
+The Actor system provides two storage types for files and results: [key-value](/platform/actors/development/actor-definition/key-value-store-schema) store and [dataset](/platform/actors/development/actor-definition/dataset-schema).
 
-Running the Actor locally allows you to test and debug your code before deploying it to the Apify platform.
+#### Key-value store
 
-:::
+The key-value store saves and reads files or data records. Key-value stores work well for screenshots, PDFs, or persisting Actor state as JSON files.
+
+#### Dataset
+
+The dataset stores a series of data objects from web scraping, crawling, or data processing jobs. You can export datasets to JSON, CSV, XML, RSS, Excel, or HTML formats.
+
+### Actor's `output`
+
+You define the Actor output using the Output schema files:
 
-## Deploy it to Apify platform
+- [Dataset Schema Specification](/platform/actors/development/actor-definition/dataset-schema)
+- [Key-value Store Schema Specification](/platform/actors/development/actor-definition/key-value-store-schema)
 
-Once you are satisfied with your Actor, to deploy it to the Apify platform, follow these steps:
+The system uses this to generate an immutable JSON file that tells users where to find the Actor's results.
 
-1. _Sign in to Apify with the CLI tool_
+## Step 4: Deploy your Actor
+
+Let's now deploy your Actor to the Apify platform, where you can run the Actor on a scheduled basis, or you can make the Actor public for other users.
+
+1. Login first:
 
     ```bash
     apify login
     ```
 
-    This command will prompt you to provide your API token that you can find in Console.
+    :::info Your Apify token location
 
-1. _Push your Actor to the Apify platform_
+    After you successfully login, your Apify token is stored in `~/.apify/auth.json`, or `C:\Users\<name>\.apify` based on your system.
+
+    :::
+
+2. 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
+## Step 5: It's Time to Iterate!
 
-    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.
+Good job! 🎉 You're ready to develop your Actor. You can make changes to your Actor and implement your use case.
 
-    :::
+## Next steps
 
-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.
+- Visit the [Apify Academy](/academy) to access a comprehensive collection of tutorials, documentation, and learning resources.
+- To understand Actors in detail, read the [Actor Whitepaper](https://whitepaper.actor/).
+- Check [Continuous integration](../deployment/continuous_integration.md) documentation to automate your Actor development process.
+- After you finish building your first Actor, you can [share it with other users and even monetize it](../../publishing/index.mdx).