diff --git a/docs/website/blog/2023-05-26-structured-data-lakes-through-schema-evolution-next-generation-data-platform.md b/docs/website/blog/2023-05-26-structured-data-lakes-through-schema-evolution-next-generation-data-platform.md
index 09a558555a..d47b9a5b72 100644
--- a/docs/website/blog/2023-05-26-structured-data-lakes-through-schema-evolution-next-generation-data-platform.md
+++ b/docs/website/blog/2023-05-26-structured-data-lakes-through-schema-evolution-next-generation-data-platform.md
@@ -108,5 +108,5 @@ To try out schema evolution with `dlt`, check out our [colab demo.](https://cola
 ### Want more?
 
 - Join our [Slack](https://join.slack.com/t/dlthub-community/shared_invite/zt-1slox199h-HAE7EQoXmstkP_bTqal65g)
-- Read our [docs on implementing schema evolution](https://dlthub.com/docs/reference/explainers/schema-evolution)
+- Read our [schema evolution blog post](https://dlthub.com/docs/blog/schema-evolution)
 - Stay tuned for the next article in the series: *How to do schema evolution with* `dlt` *in the most effective way*
\ No newline at end of file
diff --git a/docs/website/docs/reference/explainers/schema-evolution.md b/docs/website/blog/2023-06-10-schema-evolution.md
similarity index 88%
rename from docs/website/docs/reference/explainers/schema-evolution.md
rename to docs/website/blog/2023-06-10-schema-evolution.md
index f0a0e9e222..2347e95bfd 100644
--- a/docs/website/docs/reference/explainers/schema-evolution.md
+++ b/docs/website/blog/2023-06-10-schema-evolution.md
@@ -1,7 +1,12 @@
 ---
-title: Schema evolution
-description: Schema evolution with dlt
-keywords: [schema evolution, schema versioning, data contracts]
+slug: schema-evolution
+title: "Schema Evolution"
+authors:
+  name: Adrian Brudaru
+  title: Schema Evolution
+  url: https://github.com/adrianbr
+  image_url: https://avatars.githubusercontent.com/u/5762770?v=4
+tags: [data engineer shortage, structured data, schema evolution]
 ---
 
 # Schema evolution
@@ -131,10 +136,10 @@ business-logic tests, you would still need to implement them in a custom way.
 ## The implementation recipe
 
 1. Use `dlt`. It will automatically infer and version schemas, so you can simply check if there are
-   changes. You can just use the [normaliser + loader](../../general-usage/pipeline.md) or
-   [build extraction with dlt](../../general-usage/resource.md). If you want to define additional
-   constraints, you can do so in the [schema](../../general-usage/schema.md).
-1. [Define your slack hook](../../running-in-production/running.md#using-slack-to-send-messages) or
+   changes. You can just use the [normaliser + loader](https://dlthub.com/docs/general-usage/pipeline.md) or
+   [build extraction with dlt](https://dlthub.com/docs/general-usage/resource.md). If you want to define additional
+   constraints, you can do so in the [schema](https://dlthub.com/docs/general-usage/schema.md).
+1. [Define your slack hook](https://dlthub.com/docs/running-in-production/running.md#using-slack-to-send-messages) or
    create your own notification function. Make sure the slack channel contains the data producer and
    any stakeholders.
-1. [Capture the load job info and send it to the hook](../../running-in-production/running#inspect-save-and-alert-on-schema-changes).
+1. [Capture the load job info and send it to the hook](https://dlthub.com/docs/running-in-production/running#inspect-save-and-alert-on-schema-changes).
diff --git a/docs/website/blog/2023-06-15-automating-data-engineers.md b/docs/website/blog/2023-06-15-automating-data-engineers.md
index 6228a067ab..eef291cdbe 100644
--- a/docs/website/blog/2023-06-15-automating-data-engineers.md
+++ b/docs/website/blog/2023-06-15-automating-data-engineers.md
@@ -122,5 +122,5 @@ Not only that, but doing things this way lets your team focus on what they do be
 2. Notify stakeholders and producers of data changes, so they can curate it.
 3. Don’t explore json with data engineers - let analyst explore structured data.
 
-Ready to stop the pain? Read [this explainer on how to do schema evolution with dlt](/docs/reference/explainers/schema-evolution).
+Ready to stop the pain? Read [this explainer on how to do schema evolution with dlt](https://dlthub.com/docs/blog/schema-evolution).
 Want to discuss? Join our [slack](https://join.slack.com/t/dlthub-community/shared_invite/zt-1n5193dbq-rCBmJ6p~ckpSFK4hCF2dYA).
\ No newline at end of file
diff --git a/docs/website/docs/build-a-pipeline-tutorial.md b/docs/website/docs/build-a-pipeline-tutorial.md
index 14c3a78411..078ef5999e 100644
--- a/docs/website/docs/build-a-pipeline-tutorial.md
+++ b/docs/website/docs/build-a-pipeline-tutorial.md
@@ -413,8 +413,6 @@ These governance features in `dlt` pipelines contribute to better data managemen
 compliance adherence, and overall data governance, promoting data consistency, traceability, and
 control throughout the data processing lifecycle.
 
-Read more about [schema evolution.](reference/explainers/schema-evolution.md)
-
 ### Scaling and finetuning
 
 `dlt` offers several mechanism and configuration options to scale up and finetune pipelines:
diff --git a/docs/website/docs/dlt-ecosystem/deployments/index.md b/docs/website/docs/dlt-ecosystem/deployments/index.md
new file mode 100644
index 0000000000..f3d003dea9
--- /dev/null
+++ b/docs/website/docs/dlt-ecosystem/deployments/index.md
@@ -0,0 +1,18 @@
+---
+title: Deployments
+description: dlt can run on almost any python environment and hardware
+keywords: [dlt, running, environment]
+---
+import DocCardList from '@theme/DocCardList';
+
+# Deployments
+Where Python runs, `dlt` will run too. Besides deployments you see below, our users report that they ran us successfully on:
+* notebook environments including Colab
+* orchestrators including Kestra, Prefect or Dagster
+* AWS Lambda and other serverless
+* local laptops with `duckdb` or `weaviate` as destinations
+* Github codespaces and other devcontainers
+* regular VMs from all major providers: AWS, GCP or Azure
+* containers via Docker, docker-compose and Kubernetes
+
+<DocCardList />
diff --git a/docs/website/docs/dlt-ecosystem/deployments/orchestrators/airflow-deployment.md b/docs/website/docs/dlt-ecosystem/deployments/orchestrators/airflow-deployment.md
deleted file mode 100644
index 15f00731e2..0000000000
--- a/docs/website/docs/dlt-ecosystem/deployments/orchestrators/airflow-deployment.md
+++ /dev/null
@@ -1,40 +0,0 @@
----
-title: Airflow with Cloud Composer
-description: How to run dlt pipeline with Airflow
-keywords: [dlt, webhook, serverless, airflow, gcp, cloud composer]
----
-
-# Deployment with Airflow and Google Cloud Composer
-
-[Airflow](https://airflow.apache.org) is like your personal assistant for managing data workflows.
-It's a cool open-source platform that lets you create and schedule complex data pipelines. You can
-break down your tasks into smaller chunks, set dependencies between them, and keep an eye on how
-everything's running.
-
-[Google Cloud Composer](https://cloud.google.com/composer) is a Google Cloud managed Airflow, which
-allows you to use Airflow without having to deploy it. It costs the same as you would run your own,
-except all the kinks and inefficiencies have mostly been ironed out. The latest version they offer
-features autoscaling which helps reduce cost further by shutting down unused workers.
-
-Combining Airflow, `dlt`, and Google Cloud Composer is a game-changer. You can supercharge your data
-pipelines by leveraging Airflow's workflow management features, enhancing them with `dlt`'s
-specialized templates, and enjoying the scalability and reliability of Google Cloud Composer's
-managed environment. It's the ultimate combo for handling data integration, transformation, and
-loading tasks like a pro.
-
-`dlt` makes it super convenient to deploy your data load script and integrate it seamlessly with
-your Airflow workflow in Google Cloud Composer. It's all about simplicity and getting things done
-with just a few keystrokes.
-
-For this easy style of deployment, `dlt` supports
-[the cli command](../../../reference/command-line-interface.md#airflow-composer):
-
-```bash
-dlt deploy {pipeline_script}.py airflow-composer
-```
-
-which generates the necessary code and instructions.
-
-Read our
-[Walkthroughs: Deploy a pipeline with Airflow and Google Composer](../../../walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer.md)
-to find out more.
diff --git a/docs/website/docs/dlt-ecosystem/deployments/orchestrators/choosing-an-orchestrator.md b/docs/website/docs/dlt-ecosystem/deployments/orchestrators/choosing-an-orchestrator.md
deleted file mode 100644
index 76d6389a1e..0000000000
--- a/docs/website/docs/dlt-ecosystem/deployments/orchestrators/choosing-an-orchestrator.md
+++ /dev/null
@@ -1,120 +0,0 @@
----
-title: Choosing an orchestrator
-description: How to choose an orchestrator to deploy dlt pipeline
-keywords: [orchestrator, airflow, github actions]
----
-
-# Choosing an orchestrator
-
-Orchestrators enable developers to quickly and easily deploy and manage applications in the cloud.
-
-## What is an orchestrator?
-
-An orchestrator is a software system that automates the deployment, scaling, and management of
-applications and services.
-
-It provides a single platform for managing and coordinating the components of distributed
-applications, including containers, microservices, and other cloud-native resources.
-
-## Do I need an orchestrator?
-
-No, but if you do not use one, you will need to consider how to solve the problems one would:
-
-- Monitoring, Alerting;
-- deployment and execution;
-- scheduling complex workflows;
-- task triggers, dependencies, retries;
-- UI for visualising workflows;
-- secret vaults/storage;
-
-So in short, unless you need something very lightweight, you can benefit from an orchestrator.
-
-## So which one?
-
-### **Airflow**
-
-Airflow is a market standard that’s hard to beat. Any shortcomings it might have is more than
-compensated for by being an open source mature product with a large community.
-
-`dlt` supports **airflow deployments**, meaning it’s particularly easy to deploy `dlt` pipelines to
-Airflow via simple commands.
-
-Your Airflow options are:
-
-1. Broadly used managed Airflow vendors:
-
-   - [GCP Cloud Composer](https://cloud.google.com/composer?hl=en) is
-     recommended due to GCP being easy to use for non engineers and Google BigQuery being a popular
-     solution.
-   - [Astronomer.io](http://Astronomer.io) (recommended for non GCP users). CI/CD out of the box
-   - AWS has a managed Airflow too, though it is the hardest to use.
-
-1. Self-managed Airflow:
-
-   - You can self-host and run your own Airflow. This is not recommended unless the team plans to
-     have the skills to work with this in house.
-
-Limitations:
-
-- Airflow manages large scale setups and small alike.
-
-To deploy a pipeline on Airflow with Google Composer, read our
-[step-by-step tutorial](../../../walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer) about
-using the `dlt deploy` command.
-
-### **GitHub Actions**
-
-GitHub Actions is not a full-blown orchestrator, but it works. It supports simple workflows and
-scheduling, allowing for a visual, lightweight deployment with web-based monitoring (i.e. you can
-see runs in GitHub Actions). It has a free tier, but its pricing is not convenient for large jobs.
-
-To deploy a pipeline on GitHub Actions, read
-[here](../../../walkthroughs/deploy-a-pipeline/deploy-with-github-actions) about using the
-`dlt deploy` command and
-[here](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration)
-about the limitations of GitHub Actions and how their billing works.
-
-### **Other orchestrators**
-
-Other orchestrators can also do the job, so if you are limited in choice or prefer something else,
-choose differently. If your team prefers a different tool which affects their work positively,
-consider that as well.
-
-What do you need to consider when using other orchestrators?
-
-## Source - Resource decomposition:
-
-You can decompose a pipeline into strongly connected components with
-`source().decompose(strategy="scc")`. The method returns a list of dlt sources each containing a
-single component. Method makes sure that no resource is executed twice.
-
-Serial decomposition:
-
-You can load such sources as tasks serially in order present of the list. Such DAG is safe for
-pipelines that use the state internally.
-[It is used internally by our Airflow mapper to construct DAGs.](https://github.com/dlt-hub/dlt/blob/devel/dlt/helpers/airflow_helper.py)
-
-Custom decomposition:
-
-- When decomposing pipelines into tasks, be mindful of shared state.
-- Dependent resources pass data to each other via hard disk - so they need to run on the same
-  worker. Group them in a task that runs them together.
-- State is per-pipeline. The pipeline identifier is the pipeline name. A single pipeline state
-  should be accessed serially to avoid losing details on parallel runs.
-
-Parallel decomposition:
-
-If you are using only the resource state (which most of the pipelines really should!) you can run
-your tasks in parallel.
-
-- Perform the `scc` decomposition.
-- Run each component in a pipeline with different but deterministic `pipeline_name` (same component
-  \- same pipeline, you can use names of selected resources in source to construct unique id).
-
-Each pipeline will have its private state in the destination and there won't be any clashes. As all
-the components write to the same schema you may observe a that loader stage is attempting to migrate
-the schema, that should be a problem though as long as your data does not create variant columns.
-
-## Credentials
-
-[See credentials section for passing credentials to or from dlt.](../../../general-usage/credentials.md)
diff --git a/docs/website/docs/dlt-ecosystem/deployments/orchestrators/github-actions.md b/docs/website/docs/dlt-ecosystem/deployments/orchestrators/github-actions.md
deleted file mode 100644
index 8a5d693117..0000000000
--- a/docs/website/docs/dlt-ecosystem/deployments/orchestrators/github-actions.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-title: GitHub Actions
-description: How to run dlt in GitHub Actions
-keywords: [dlt, webhook, serverless, deploy, github actions]
----
-
-# Native deployment to GitHub Actions
-
-What is a native deployment to dlt? A native deployment is a deployment where dlt will generate the
-glue code and credentials instructions.
-
-[GitHub Actions](https://docs.github.com/en/actions) is an automation tool by GitHub for building,
-testing, and deploying software projects. It simplifies development with pre-built actions and
-custom workflows, enabling tasks like testing, documentation generation, and event-based triggers.
-It streamlines workflows and saves time for developers.
-
-When `dlt` and GitHub Actions join forces, data loading and software development become a breeze.
-Say goodbye to manual work and enjoy seamless data management.
-
-For this easy style of deployment, dlt supports the
-[cli command](../../../reference/command-line-interface#github-action):
-
-```shell
-dlt deploy <script>.py github-action --schedule <cron schedule>
-```
-
-which generates the necessary code and instructions.
-
-> 💡 Read our
-> [Walkthroughs: Deploy a pipeline with GitHub Actions](../../../walkthroughs/deploy-a-pipeline/deploy-with-github-actions)
-> to find out more.
diff --git a/docs/website/docs/dlt-ecosystem/deployments/running-in-cloud-functions.md b/docs/website/docs/dlt-ecosystem/deployments/running-in-cloud-functions.md
deleted file mode 100644
index daab955f20..0000000000
--- a/docs/website/docs/dlt-ecosystem/deployments/running-in-cloud-functions.md
+++ /dev/null
@@ -1,49 +0,0 @@
----
-title: Running in Cloud Functions
-description: How to run dlt in serverless functions
-keywords: [dlt, webhook, serverless]
----
-
-# Why run in Cloud Functions? Use cases and limitations
-
-## Real time data stream processing:
-
-Real time data ingestion and usage architectures usually take the following steps:
-
-1. Collect raw data in a buffer. For this we might use streaming technologies or some ad hoc buffer.
-1. Periodically read the buffer and process the data. Here we often use a serverless function that
-   can validate schemas and load the data to the next stage.
-
-The reason we use cloud functions for this case is that cloud functions can be spawned in parallel,
-allowing us to scale gracefully. For example, if we call a function to process every chunk of X
-size, then if the data volume varies, the only thing that changes is how many functions we call.
-
-## Event-driven Data Processing (Webhooks, etc.)
-
-Some applications can send events as they happen, and in order to capture them, you need an "always
-up" listener application.
-
-To implement event-driven data processing with serverless cloud functions, you typically follow
-these steps:
-
-1. Configure Event Source: Set up the event source, such as a webhook provider, to send events to
-   the cloud function. This involves defining the event triggers, authentication mechanisms, and any
-   required event payload or metadata.
-1. Develop Cloud Function: Write the event processing logic in the chosen cloud function programming
-   language. This logic defines how the incoming event data is processed, transformed, stored, or
-   integrated with other systems or services. `dlt` enables you to validate schemas and process events
-   in this step.
-1. Deploy and Configure Cloud Function: Deploy the cloud function to the serverless function
-   platform, such as AWS Lambda, Google Cloud Functions, or Azure Functions. Configure the function
-   settings, including resource allocation, timeouts, and any required environment variables or
-   dependencies.
-
-## Batch ingestion
-
-Cloud functions offer a powerful alternative for batch ingestion. Due to the possibility to run
-multiple instances in parallel, using cloud functions to process data gives you easy access to
-scalable compute, and can help you achieve consistent processing times.
-
-> 💡 Read our
-> [Walkthroughs: Deploy a pipeline with Google Cloud Functions](../../walkthroughs/deploy-a-pipeline/deploy-with-google-cloud-functions)
-> to find out more.
diff --git a/docs/website/docs/dlt-ecosystem/deployments/where-can-dlt-run.md b/docs/website/docs/dlt-ecosystem/deployments/where-can-dlt-run.md
deleted file mode 100644
index e67d554c70..0000000000
--- a/docs/website/docs/dlt-ecosystem/deployments/where-can-dlt-run.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: Where can dlt run?
-description: dlt can run on almost any python environment and hardware
-keywords: [dlt, running, environment]
----
-
-# Where can dlt run?
-
-## Made for your environments: Airflow, GCP Cloud Functions, AWS Lambda, GitHub Actions
-
-Scaling data pipelines presents unique challenges:
-
-- How much RAM we need to process the data - are we reading gigs in memory, or are we limiting
-  memory usage?
-- How much compute resource we need to process the data - should we parallelize to leverage more
-  threads or machines?
-
-And because from pipeline to pipeline data volumes may vary 10000x, then the answer is you will not
-know upfront how to scale.
-
-So you either prepare for scaling, or prepare for maintenance. `dlt` is already prepared for scaling.
-
-- It can run in [Cloud Functions](running-in-cloud-functions.md) - you could use it to receive events and load them, or to process
-  events from a buffer.
-- It can run on Airflow - where most data pipelines run nowadays. We support
-  [deployment to Airflow](orchestrators/airflow-deployment.md) here.
-- It can run on Git Actions - we even support the
-  [Github Actions deployment command](orchestrators/github-actions.md) here.
-
-### Memory and compute management
-
-While you can pass any data to `dlt`, `dlt` prefers sources as generators, because this enables `dlt` to
-manage how much data it loads into memory at a time.
-
-By managing the maximum size of the memory buffer for extraction, `dlt` can process large data sources
-chunk by chunk and not run out of ram.
-
-After the data is downloaded, `dlt` may spawn multiple parallel processes to normalise the data - they
-will also do it chunk by chunk, to avoid filling the ram.
-
-This way, with `dlt`:
-
-- Large data can be processed on tiny machines. No more crashing Airflow workers or pods.
-- When normalising data, we use the available compute resources optimally.
-- By enabling running on micro workers, you are enabled to split your job before running it with
-  `dlt`, to achieve more parallelism.
-
-### Python env, dependencies
-
-You can run `dlt` directly on your python interpreter, or you could create a venv to isolate its
-dependencies. Read more about [installing dlt](../../reference/installation.mdx) here.
-
-`dlt` is designed with minimal dependency footprint. Once you install `dlt`, you may also need to
-install the destination package. The instructions to do so will appear when you init a pipeline with
-a different destination. For example, initing a BigQuery pipeline will create a requirements file
-with `dlt[bigquery]` in it, and you will be asked to pip install it.
diff --git a/docs/website/docs/general-usage/import-dlt.md b/docs/website/docs/general-usage/import-dlt.md
deleted file mode 100644
index 9d675eebff..0000000000
--- a/docs/website/docs/general-usage/import-dlt.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: Import dlt
-description: How to import dlt
-keywords: [import, importing dlt]
----
-
-# Import `dlt`
-
-To use `dlt` functions, please import the `dlt` library:
-
-```python
-import dlt
-```
-
-In the `dlt` module you can:
-
-1. Define and run [pipelines](pipeline.md) with `dlt.pipeline`.
-1. Declare [sources](source.md) and [resources](resource.md) using `@dlt.source` and `@dlt.resource`
-   decorators.
-1. Define and access [configuration](configuration.md) values and [credentials](credentials.md)
-   with `dlt.config` and `dlt.secrets`.
-1. Access the current pipeline [state](state.md) using `dlt.current.state` in your sources and
-   resources as well as the current schema and pipeline.
diff --git a/docs/website/docs/general-usage/state.md b/docs/website/docs/general-usage/state.md
index 50896042a0..8b039d9f3d 100644
--- a/docs/website/docs/general-usage/state.md
+++ b/docs/website/docs/general-usage/state.md
@@ -53,15 +53,17 @@ to their displayable names. You can take a look at our
 [pipedrive source](https://github.com/dlt-hub/verified-sources/blob/master/sources/pipedrive/__init__.py#L118)
 for an example of state passed across resources.
 
-> 💡 Avoid the use of shared state if you plan to
-> [decompose your source](../dlt-ecosystem/deployments/orchestrators/choosing-an-orchestrator.md#source---resource-decomposition)
-> in order to, for example run it on Airflow in parallel. If you cannot avoid that, designate one of
-> the resources as state writer and all the other as state readers. This is exactly what `pipedrive`
-> pipeline does. With such structure you will still be able to run some of your resources in
-> parallel.
-
-> ❗ The `dlt.state()` is a deprecated alias to `dlt.current.source_state()` and will be soon
-> removed.
+:::tip
+[decompose your source](../reference/performance.md#source-decomposition-for-serial-and-parallel-resource-execution)
+in order to, for example run it on Airflow in parallel. If you cannot avoid that, designate one of
+the resources as state writer and all the other as state readers. This is exactly what `pipedrive`
+pipeline does. With such structure you will still be able to run some of your resources in
+parallel.
+:::
+:::caution
+The `dlt.state()` is a deprecated alias to `dlt.current.source_state()` and will be soon
+removed.
+:::
 
 ## Syncing state with destination
 
diff --git a/docs/website/docs/reference/airflow-gcp-cloud-composer.md b/docs/website/docs/reference/explainers/airflow-gcp-cloud-composer.md
similarity index 95%
rename from docs/website/docs/reference/airflow-gcp-cloud-composer.md
rename to docs/website/docs/reference/explainers/airflow-gcp-cloud-composer.md
index 1c2ca082b0..346a3e7e71 100644
--- a/docs/website/docs/reference/airflow-gcp-cloud-composer.md
+++ b/docs/website/docs/reference/explainers/airflow-gcp-cloud-composer.md
@@ -10,7 +10,7 @@ keywords: [airflow, github, google cloud composer]
 
 This setup will allow you to deploy the main branch of your Airflow project from GitHub to Cloud Composer.
 
-- Create a GitHub repository ie. [by following our deployment walkthroughs for Airflow](../walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer.md)
+- Create a GitHub repository ie. [by following our deployment walkthroughs for Airflow](../../walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer.md)
 
 - In Google Cloud web interface, go to Source Repositories and create a repository that mirrors your
   GitHub repository. This will simplify the authentication by doing it through this mirroring
diff --git a/docs/website/docs/reference/performance.md b/docs/website/docs/reference/performance.md
index 7a089ce7a6..f268023811 100644
--- a/docs/website/docs/reference/performance.md
+++ b/docs/website/docs/reference/performance.md
@@ -286,7 +286,7 @@ def read_table(limit):
         yield [{"row": _id, "description": "this is row with id {_id}", "timestamp": now} for _id in item_slice]
 
 
-# this prevents the process pool to run the initialization code again
+# this prevents process pool to run the initialization code again
 if __name__ == "__main__" or "PYTEST_CURRENT_TEST" in os.environ:
     pipeline = dlt.pipeline("parallel_load", destination="duckdb", full_refresh=True)
     pipeline.extract(read_table(1000000))
@@ -303,6 +303,40 @@ if __name__ == "__main__" or "PYTEST_CURRENT_TEST" in os.environ:
 <!--SNIPEND -->
 
 
+### Source decomposition for serial and parallel resource execution
+
+You can decompose a pipeline into strongly connected components with
+`source().decompose(strategy="scc")`. The method returns a list of dlt sources each containing a
+single component. Method makes sure that no resource is executed twice.
+
+**Serial decomposition:**
+
+You can load such sources as tasks serially in order present of the list. Such DAG is safe for
+pipelines that use the state internally.
+[It is used internally by our Airflow mapper to construct DAGs.](https://github.com/dlt-hub/dlt/blob/devel/dlt/helpers/airflow_helper.py)
+
+**Parallel decomposition**
+
+If you are using only the resource state (which most of the pipelines really should!) you can run
+your tasks in parallel.
+
+- Perform the `scc` decomposition.
+- Run each component in a pipeline with different but deterministic `pipeline_name` (same component
+  \- same pipeline, you can use names of selected resources in source to construct unique id).
+
+Each pipeline will have its private state in the destination and there won't be any clashes. As all
+the components write to the same schema you may observe a that loader stage is attempting to migrate
+the schema, that should be a problem though as long as your data does not create variant columns.
+
+**Custom decomposition**
+
+- When decomposing pipelines into tasks, be mindful of shared state.
+- Dependent resources pass data to each other via generators - so they need to run on the same
+  worker. Group them in a task that runs them together - otherwise some resources will be extracted twice.
+- State is per-pipeline. The pipeline identifier is the pipeline name. A single pipeline state
+  should be accessed serially to avoid losing details on parallel runs.
+
+
 ## Resources extraction, `fifo` vs. `round robin`
 
 When extracting from resources, you have two options to determine what the order of queries to your
diff --git a/docs/website/docs/user-guides/analytics-engineer.md b/docs/website/docs/user-guides/analytics-engineer.md
deleted file mode 100644
index a322c0ae17..0000000000
--- a/docs/website/docs/user-guides/analytics-engineer.md
+++ /dev/null
@@ -1,79 +0,0 @@
----
-title: Analytics Engineer
-description: A guide to using dlt for Analytics Engineers
-keywords: [analytics engineer, analytics, business intelligence]
----
-
-# Analytics Engineer
-
-## Use Case #1: `dbt` packages for existing `dlt` pipelines
-
-### Using `dbt` packages with `dlt` pipelines
-
-
-`dlt` automatically structures unstructured data by default. This means that typically the loaded
-data structure is a cleaned, typed, and normalized version of the initial unstructured data.
-
-Since the loaded data is just a reflexion of the input raw structure, this data usually needs to be
-rearranged to get it to a structure that analysts and other business users can use to answer questions.
-For example, you will often want to consolidate this data into table that represent the business processes
-and entities involved, to make it easier for downstream consumers.
-
-
-To enable analysts to easily run `dbt` packages without dependency clashes or deployment difficulties,
-`dlt` supports a `dbt` runner that allows you to create a virtual environment,
-install `dbt` on it, pass it credentials, and run a `dbt` package from a local or online location. You
-can read more about this [here](../dlt-ecosystem/transformations).
-
-
-### Contributing `dbt` packages
-
-#### What to contribute?
-
-Great data models require a deep understanding of the data and are not easy to build. If you take
-the time to create a `dbt` package for a `dlt` pipeline, we encourage you to contribute it, so the
-community can benefit from your hard work.
-
-We are especially interested in `dbt` packages that:
-
-- Transition the pipeline data into 3rd normal form, supporting a more simple use of the data and
- the creation of an Inmon architecture data warehouse.
-- Transition the pipeline data into a dimensional model, supporting pivot-table style usage via
- query builders by business users.
-
-#### How to contribute?
-
-Follow the [contributing guide](https://github.com/dlt-hub/verified-sources/blob/master/CONTRIBUTING.md)
-in `verified-sources` repo.
-
-## Use Case #2: Clean, type, and customize how data is produced and loaded
-
-`dlt` allows you to customize how data is produced, enabling you to rename, filter, and modify the
-data that arrives at your destination. Before you pass the data to `dlt` for normalization, you can
-transform the data in Python. After `dlt` has normalized and loaded the data, you can also further
-transform it using SQL. You can learn more about possible customizations in the docs (e.g.
-[pseudonymizing columns](../general-usage/customising-pipelines/pseudonymizing_columns.md)).
-
-## Use Case #3: Create your own pipelines in a declarative fashion and supercharge your `dbt` packages
-
-dbt is always going to be dependant on the upstream pipeline creating a schema - so for the first time you
-can supercharge `dbt` users with a pipeline to make them independent.
-
-`dlt` follows similar user paradigms as dbt, enabling instant recognition and a zero learning
-curve to use the declarative loading style.
-
-`dlt` was designed from the start for the open source data tool users. It enables people who have
-never before built a data pipeline to go from raw data in Python to structured data in a database in
-minutes. For example, using DuckDB, you can easily develop your pipeline locally without needing to
-set up and connect to your production warehouse.
-
-It features a declarative approach to configuring loading modes, handling all of the engineering for
-you by default, allowing you to leverage a great loader that comes complete with support for schema
-migrations, data typing, performance hint declarations, schema management, etc.
-
-If you combine it with a `dbt` package, you enable end to end analytics engineering - if the `dbt`
-package is the main citizen, then let `dlt` be it's rocket engine.
-
-Read more about [running `dbt` packages](../dlt-ecosystem/transformations/dbt.md),
-[incremental loading](../general-usage/incremental-loading), and
-[performance hints and schemas](../walkthroughs/adjust-a-schema).
diff --git a/docs/website/docs/user-guides/data-beginner.md b/docs/website/docs/user-guides/data-beginner.md
deleted file mode 100644
index 69b8b8bdee..0000000000
--- a/docs/website/docs/user-guides/data-beginner.md
+++ /dev/null
@@ -1,130 +0,0 @@
----
-title: Data Beginner
-description: A guide to using dlt for aspiring data professionals
-keywords: [beginner, analytics, machine learning]
----
-
-# Data Beginner
-
-If you are an aspiring data professional, here are some ways you can showcase your understanding and
-value to data teams with the help of `dlt`.
-
-## Analytics: Empowering decision-makers
-
-Operational users at a company need general business analytics capabilities to make decisions, e.g.
-dashboards, data warehouse, self-service, etc.
-
-### Show you can deliver results, not numbers
-
-The goal of such a project is to get you into the top 5% of candidates, so you get invited to an
-interview and understand pragmatically what is expected of you.
-
-Depending on whether you want to be more in engineering or analytics, you can focus on different
-parts of this project. If you showcase that you are able to deliver end to end, there remains little
-reason for a potential employer to not hire you.
-
-Someone hiring folks on this business analytics path will be looking for the following skills:
-
-- Can you load data to a db?
-  - Can you do incremental loading?
-  - Are your pipelines maintainable?
-  - Are your pipelines reusable? Do they take meaningful arguments?
-- Can you transform the data to a standard architecture?
-  - Do you know dimensional modelling architecture?
-  - Does your model make the data accessible via a user facing tool to a business user?
-  - Can you translate a business requirement into a technical requirement?
-- Can you identify a use case and prepare reporting?
-  - Are you displaying a sensible use case?
-  - Are you taking a pragmatic approach as to what should be displayed and why?
-  - Did you hard code charts in a notebook that the end user cannot use or did you use a user-facing
-    dashboard tool?
-  - Is the user able to answer follow-up questions by changing the dimensions in a tool or did you
-    hard code queries?
-
-Project idea:
-
-1. Choose an API that produces data. If this data is somehow business relevant, that’s better. Many
-   business apps offer free developer accounts that allow you to develop business apps with them.
-1. Choose a use case for this data. Make sure this use case makes some business sense and is not
-   completely theoretical. Business understanding and pragmatism are key for such roles, so do not
-   waste your chance to show it. Keep the use case simple-otherwise it will not be pragmatic right
-   off the bat, handicapping yourself from a good outcome. A few examples are ranking leads in a
-   sales CRM, clustering users, and something around customer lifetime value predictions.
-1. Build a dlt pipeline that loads data from the API for your use case. Keep the case simple and
-   your code clean. Use explicit variable and method names. Tell a story with your code. For loading
-   mode, use incremental loading and don’t hardcode parameters that are subject to change.
-1. Build a [dbt package](../dlt-ecosystem/transformations/dbt.md) for this pipeline.
-1. Build a visualization. Focus on usability more than code. Remember, your goal is to empower a
-   business user to self-serve, so hard coded dashboards are usually seen as liabilities that need
-   to be maintained. On the other hand, dashboard tools can be adjusted by business users too. For
-   example, the free “Looker studio” fro Google is relatable to business users, while notebooks
-   might make them feel insecure. Your evaluator will likely not take time to set up and run your
-   things, so make sure your outcomes are well documented with images. Make sure they are self
-   readable, explain how you intend the business user to use this visualization to fulfil the use
-   case.
-1. Make it presentable somewhere public, such as GitHub, and add docs. Show it to someone for
-   feedback. You will find likeminded people in
-   [our Slack](https://join.slack.com/t/dlthub-community/shared_invite/zt-1slox199h-HAE7EQoXmstkP_bTqal65g)
-   that will happily give their opinion.
-
-## Machine Learning: Automating decisions
-
-Solving specific business problems with data products that generate further insights and sometimes
-automate decisions.
-
-### Show you can solve business problems
-
-Here the challenges might seem different from the business analytics path, but they are often quite
-similar. Many courses focus on statistics and data science but very few focus on pragmatic
-approaches to solving business problems in organizations. Most of the time, the largest obstacles to
-solving a problem with ML are not purely algorithmic but rather about the semantics of the business,
-data, and people who need to use the data products.
-
-Employers look for a project that showcases both technical ability and business pragmatism in a use
-case. In reality, data does not typically come in files but via APIs with fresh data, where you
-usually will have to grab it and move it somewhere to use, so show your ability to deliver end to
-end.
-
-Project idea:
-
-1. Choose an API that produces data. If this data is somehow business relevant, that’s better. Many
-   business apps offer free developer accounts that allow you to develop business apps with them.
-1. Choose a use case for this data. Make sure this use case makes some business sense and is not
-   completely theoretical. Business understanding and pragmatism are key for such roles, so do not
-   waste your chance to show it. Keep the use case simple-otherwise it will not be pragmatic right
-   off the bat, handicapping yourself from a good outcome. A few examples are ranking leads in a
-   sales CRM, clustering users, and something around customer lifetime value predictions.
-1. Build a dlt pipeline that loads data from the API for your use case. Keep the case simple and
-   your code clean. Use explicit variable and method names. Tell a story with your code. For loading
-   mode, use incremental loading and don’t hardcode parameters that are subject to change.
-1. Build a data model with SQL. If you are ambitious you could try running the SQL with a
-   [dbt package](../dlt-ecosystem/transformations).
-1. Showcase your chosen use case that uses ML or statistics to achieve your goal. Don’t forget to
-   mention how you plan to do this “in production”. Choose a case that is simple so you don’t end up
-   overcomplicating your solution. Focus on outcomes and next steps. Describe what the company needs
-   to do to use your results, demonstrating that you understand the costs of your propositions.
-1. Make it presentable somewhere public, such as GitHub, and add docs. Show it to someone for
-   feedback. You will find likeminded people in
-   [our Slack](https://join.slack.com/t/dlthub-community/shared_invite/zt-1slox199h-HAE7EQoXmstkP_bTqal65g)
-   that will happily give their opinion.
-
-## Further reading
-
-Good docs pages to check out:
-
-- [Getting started.](../getting-started)
-- [Create a pipeline.](../walkthroughs/create-a-pipeline)
-- [Run a pipeline.](../walkthroughs/run-a-pipeline)
-- [Deploy a pipeline with GitHub Actions.](../walkthroughs/deploy-a-pipeline/deploy-with-github-actions)
-- [Understand the loaded data.](../dlt-ecosystem/visualizations/understanding-the-tables)
-- [Explore the loaded data in Streamlit.](../dlt-ecosystem/visualizations/exploring-the-data.md)
-- [Transform the data with SQL or python.](../dlt-ecosystem/transformations)
-- [Contribute a pipeline.](https://github.com/dlt-hub/verified-sources/blob/master/CONTRIBUTING.md)
-
-Here are some example projects:
-
-- [Is DuckDB a database for ducks? Using DuckDB to explore the DuckDB open source community.](https://colab.research.google.com/drive/1NfSB1DpwbbHX9_t5vlalBTf13utwpMGx?usp=sharing)
-- [Using DuckDB to explore the Rasa open source community.](https://colab.research.google.com/drive/1c9HrNwRi8H36ScSn47m3rDqwj5O0obMk?usp=sharing)
-- [MRR and churn calculations on Stripe data.](../dlt-ecosystem/verified-sources/stripe.md)
-
-Please [open a PR](https://github.com/dlt-hub/verified-sources) to add projects that use `dlt` here!
diff --git a/docs/website/docs/user-guides/data-engineer.md b/docs/website/docs/user-guides/data-engineer.md
deleted file mode 100644
index 9fb48b5907..0000000000
--- a/docs/website/docs/user-guides/data-engineer.md
+++ /dev/null
@@ -1,97 +0,0 @@
----
-title: ETL Engineer
-description: A guide to using dlt for Data Engineers
-keywords: [data engineer, de, pipeline builder, ETL engineer]
----
-
-# ETL Engineer
-
-## Use Case #1: Remove a big chunk of tedious work and most ETL maintenance
-
-With `dlt`, you can automate the transition from unstructured (nested, untyped) to structured
-(tabular, typed) data.
-
-`dlt` is a library that you can use almost anywhere, so you are not forced to use some prescribed
-way of doing things. The simplest usage of dlt would be to use it as an unstructured to structured
-data transition tool in your existing code.
-
-A `dlt` pipeline is made of a source, which contains resources, and a connection to the destination,
-which we call pipeline. So in the simplest use case, you could pass your unstructured data to the
-`pipeline` and it will automatically be migrated to structured at the destination. See how to do
-that here [pipeline docs](../general-usage/pipeline).
-
-The big advantage of using dlt for this is that it automates what is otherwise an error prone and
-tedious operation for the data engineer. What’s more, `dlt` can migrate schemas, removing not only
-development work but also most of the maintenance work as well. Read more about [how to monitor
-schema evolution](../running-in-production/running#inspect-save-and-alert-on-schema-changes).
-
-## Use Case #2: Empower everyone on the team with a library
-
-`dlt` is meant to be accessible to each person on the data team, enabling you to standardize how
-your entire team loads data. This reduces knowledge requirements to get work done and enables
-collaborative working between engineers and analysts.
-
-- Analysts can use ready-built sources or pass their unstructured data to `dlt`, which will create a
-  sturdy pipeline (e.g. [get an existing source](../walkthroughs/add-a-verified-source),
-  [build a pipeline](../walkthroughs/create-a-pipeline)).
-- Python-first users can heavily customize how dlt sources produce data, as dlt supports selecting,
-  filtering, renaming, anonymizing, and just about any custom operation (e.g.
-  [rename columns example](../general-usage/customising-pipelines/renaming_columns.md)).
-- Junior data engineers can configure dlt to do what they want-change the loading modes, add
-  performance hints, etc. (e.g. [adjust a schema](../walkthroughs/adjust-a-schema)).
-- Senior data engineers can dig even deeper into customization options and change schemas,
-  normalizers, the way pipelines run such as parallelism, etc.
-
-## Use Case #3: Enhance your productivity with `dlt`
-
-`dlt` is meant to support natural workflows that occur in the data team. Offering native support for
-local development and testing, you can use `dlt` with a local duckdb destination and use
-`dlt pipeline show` to generate a web client to display and query the data. Once you are happy with
-it, you can simply switch to your production destination and you pipeline will run on production
-from the first try (e.g. [show data](../dlt-ecosystem/visualizations/exploring-the-data.md),
-[Colab DuckDB example](https://colab.research.google.com/drive/1NfSB1DpwbbHX9_t5vlalBTf13utwpMGx?usp=sharing)).
-
-With dbt runner, you can additionally develop and later run transformations. If you use cross-db
-compatibility for dbt, your code can even be developed locally such as on DuckDB or reused by others
-if you choose to share your code (e.g.
-[run dbt from local or repository](../dlt-ecosystem/transformations/dbt.md)).
-
-`dlt` supports Airflow and other workflow managers. It’s meant to plug into your data stack without
-causing more overheads (e.g.
-[how to set up on Airflow](../walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer.md)).
-
-`dlt` also allows easy customization and maintenance of the code-`dlt` sources are pythonic and
-simple, so no object oriented programming required. Your junior data scientist can fix and customize
-the pipelines too (e.g.
-[Strapi example](https://github.com/dlt-hub/verified-sources/blob/master/sources/strapi/__init__.py)).
-
-## Use Case #4: Solve problems with a community
-
-No more reinventing the flat tyre in the form of yet another custom pipeline.
-
-- Community support. If you choose to publish your pipelines to the community, they will be reused,
-  improved, upgraded, tests added, etc.
-- Community distribution support. A verified source hosted in the public `verified-sources` repo can
-  be distributed via our command line interface. The command also handles versioning, merging,
-  upgrading, etc.
-
-Read more about our [contribution process](https://github.com/dlt-hub/verified-sources/blob/master/CONTRIBUTING.md)
-and contribute sources or request them in
-[verified sources repository](https://github.com/dlt-hub/verified-sources).
-
-## Inheriting a running `dlt` pipeline
-
-If you are taking over a `dlt` pipeline that someone else built or set up, you are in luck! What's
-important to know:
-
-- The pipeline is largely self-maintaining. The only thing you must ensure is that the source keeps
-  producing data-from there dlt handles it.
-- You can notify schema evolution events (e.g.
-  [alert schema change](../running-in-production/running#inspect-save-and-alert-on-schema-changes)).
-- You can use the data by transforming it with dbt (e.g.
-  [run dbt from local or repository](../dlt-ecosystem/transformations/dbt.md)).
-- If the sources used are public, you can update your pipelines to the latest version from the
-  online repo with the `dlt init`command. If you are the first to fix, you can contribute the fix
-  back, so it will be included in the future versions (e.g.
-  [init a pipeline](../reference/command-line-interface#dlt-init),
-  [contribute a source](https://github.com/dlt-hub/verified-sources/blob/master/CONTRIBUTING.md)).
diff --git a/docs/website/docs/user-guides/data-scientist.md b/docs/website/docs/user-guides/data-scientist.md
deleted file mode 100644
index c0bcf289be..0000000000
--- a/docs/website/docs/user-guides/data-scientist.md
+++ /dev/null
@@ -1,129 +0,0 @@
----
-title: Data Scientist
-description: A guide to using dlt for Data Scientists
-keywords: [data scientist, data science, machine learning, machine learning engineer]
----
-
-
-# Data Scientist
-
-Data Load Tool (`dlt`) can be highly useful for Data Scientists in several ways. Here are three
-potential use cases:
-
-## Use case #1: Efficient Data Ingestion and Optimized Workflow
-
-Data Scientists often deal with large volumes of data from various sources. `dlt` can help
-streamline the process of data ingestion by providing a robust and scalable tool for loading data
-into their analytics environment. It can handle diverse data formats, such as CSV, JSON, or database
-dumps, and efficiently load them into a data lake or a data warehouse.
-
-![dlt-main](images/dlt-main.png)
-
-By using `dlt`, Data Scientists can save time and effort on data extraction and transformation
-tasks, allowing them to focus more on data analysis and models training. The tool is designed as a
-library that can be added to their code, making it easy to integrate into existing workflows.
-
-`dlt` can facilitate a seamless transition from data exploration to production deployment. Data
-Scientists can leverage `dlt` capabilities to load data in the format that matches the production
-environment while exploring and analyzing the data. This streamlines the process of moving from the
-exploration phase to the actual implementation of models, saving time and effort. By using `dlt`
-throughout the workflow, Data Scientists can ensure that the data is properly prepared and aligned
-with the production environment, leading to smoother integration and deployment of their models.
-
-- [Use existed Verified Sources](../walkthroughs/add-a-verified-source) and pipeline examples or
-  [create your own](../walkthroughs/create-a-pipeline) quickly.
-
-- [Deploy the pipeline](../walkthroughs/deploy-a-pipeline), so that the data is automatically loaded
-  on a schedule.
-
-- Transform the [loaded data](../dlt-ecosystem/transformations) with dbt or in
-  Pandas DataFrames.
-
-- Learn how to [run](../running-in-production/running),
-  [monitor](../running-in-production/monitoring), and [alert](../running-in-production/alerting)
-  when you put your pipeline in production.
-
-- Use `dlt` when doing exploration in a Jupyter Notebook and move more easily to production. Explore
-  our
-  [Colab Demo for Chess.com API](https://colab.research.google.com/drive/1NfSB1DpwbbHX9_t5vlalBTf13utwpMGx?usp=sharing)
-  to realize how easy it is to create and use `dlt` in your projects:
-
-  ![colab-demo](images/colab-demo.png)
-
-### `dlt` is optimized for local use on laptops
-
-- It offers a seamless
-  [integration with Streamlit](../dlt-ecosystem/visualizations/understanding-the-tables#show-tables-and-data-in-the-destination).
-  This integration enables a smooth and interactive data analysis experience, where Data Scientists
-  can leverage the power of `dlt` alongside Streamlit's intuitive interface and visualization
-  capabilities.
-- In addition to Streamlit, `dlt` natively supports
-  [DuckDB](https://dlthub.com/docs/blog/is-duckdb-a-database-for-ducks), an in-process SQL OLAP
-  database management system. This native support ensures efficient data processing and querying
-  within `dlt`, leveraging the capabilities of DuckDB. By integrating DuckDB, Data Scientists can
-  benefit from fast and scalable data operations, enhancing the overall performance of their
-  analytical workflows.
-- Moreover, `dlt` provides resources that can directly return data in the form of
-  [Pandas DataFrames from an SQL client](../dlt-ecosystem/visualizations/exploring-the-data). This
-  feature simplifies data retrieval and allows Data Scientists to seamlessly work with data in
-  familiar Pandas DataFrame format. With this capability, Data Scientists can leverage the rich
-  ecosystem of Python libraries and tools that support Pandas.
-
-With `dlt`, the transition from local storage to remote is quick and easy. For example, read the
-documentation [Share a dataset: DuckDB -> BigQuery](../walkthroughs/share-a-dataset).
-
-## Use case #2:  Structured Data and Enhanced Data Understanding
-
-### Structured data
-
-Data Scientists often prefer structured data lakes over unstructured ones to facilitate efficient
-data analysis and modeling. `dlt` can help in this regard by offering seamless integration with
-structured data storage systems, allowing Data Scientists to easily load and organize their data in
-a structured format. This enables them to access and analyze the data more effectively, improving
-their understanding of the underlying data structure.
-
-![structured-data](images/structured-data.png)
-
-A `dlt` pipeline is made of a source, which contains resources, and a connection to the destination,
-which we call pipeline. So in the simplest use case, you could pass your unstructured data to the
-`pipeline` and it will automatically be migrated to structured at the destination. See how to do
-that in our [pipeline documentation](../general-usage/pipeline).
-
-Besides strurdiness, this also adds convenience by automatically converting json types to db types,
-such as timestamps, etc.
-
-Read more about schema evolution in our blog:
-**[The structured data lake: How schema evolution enables the next generation of data platforms](https://dlthub.com/docs/blog/next-generation-data-platform).**
-
-### Data exploration
-
-Data Scientists require a comprehensive understanding of their data to derive meaningful insights
-and build accurate models. `dlt` can contribute to this by providing intuitive and user-friendly
-features for data exploration. It allows Data Scientists to quickly gain insights into their data by
-visualizing data summaries, statistics, and distributions. With `dlt`, data understanding becomes
-clearer and more accessible, enabling Data Scientists to make informed decisions throughout the
-analysis process.
-
-Besides, having a schema imposed on the data acts as a technical description of the data,
-accelerating the discovery process.
-
-See [Understanding the tables](../dlt-ecosystem/visualizations/understanding-the-tables),
-[Exploring the data](../dlt-ecosystem/visualizations/exploring-the-data) in our documentation.
-
-## Use case #3: Data Preprocessing and Transformation
-
-Data preparation is a crucial step in the data science workflow. `dlt` can facilitate data
-preprocessing and transformation tasks by providing a range of built-in features. It simplifies
-various tasks like data cleaning, anonymizing, handling missing values, data type conversion,
-feature scaling, and feature engineering. Data Scientists can leverage these capabilities to clean
-and transform their datasets efficiently, making them suitable for subsequent analysis and modeling.
-
-Python-first users can heavily customize how `dlt` sources produce data, as `dlt` supports
-selecting, [filtering](../general-usage/resource#filter-transform-and-pivot-data),
-[renaming](../general-usage/customising-pipelines/renaming_columns),
-[anonymizing](../general-usage/customising-pipelines/pseudonymizing_columns), and just about any
-custom operation.
-
-Compliance is also a case where preprocessing is the way to solve the issue: Besides being
-python-friendly, the ability to apply transformation logic before loading data allows us to
-separate, filter or transform sensitive data.
diff --git a/docs/website/docs/user-guides/engineering-manager.md b/docs/website/docs/user-guides/engineering-manager.md
deleted file mode 100644
index cdd8ad4172..0000000000
--- a/docs/website/docs/user-guides/engineering-manager.md
+++ /dev/null
@@ -1,155 +0,0 @@
----
-title: Staff Data Engineer
-description: A guide to using dlt for Staff Data Engineers
-keywords: [staff data engineer, senior data engineer, ETL engineer, head of data platform,
-  data platform engineer]
----
-
-# Staff Data Engineer
-
-Staff data engineers create data pipelines, data warehouses and data lakes in order to democratize
-access to data in their organizations.
-
-With `dlt` we offer a library and building blocks that data tool builders can use to create modern
-data infrastructure for their companies. Staff Data Engineer, Senior Data Engineer, ETL Engineer,
-Head of Data Platform - there’s a variety of titles of how data tool builders are called in
-companies.
-
-## What does this role do in an organisation?
-
-The job responsibilities of this senior vary, but often revolve around building and maintaining a
-robust data infrastructure:
-
-- Tech: They design and implement scalable data architectures, data pipelines, and data processing
-  frameworks.
-- Governance: They ensure data integrity, reliability, and security across the data stack. They
-  manage data governance, including data quality, data privacy, and regulatory compliance.
-- Strategy: Additionally, they evaluate and adopt new technologies, tools, and methodologies to
-  improve the efficiency, performance, and scalability of data processes.
-- Team skills and staffing: Their responsibilities also involve providing technical leadership,
-  mentoring team members, driving innovation, and aligning the data strategy with the organization's
-  overall goals.
-- Return on investment focus: Ultimately, their focus is on empowering the organization to derive
-  actionable insights, make data-driven decisions, and unlock the full potential of their data
-  assets.
-
-## Choosing a Data Stack
-
-The above roles play a critical role in choosing the right data stack for their organization. When
-selecting a data stack, they need to consider several factors. These include:
-
-- The organization's data requirements.
-- Scalability, performance, data governance and security needs.
-- Integration capabilities with existing systems and tools.
-- Team skill sets, budget, and long-term strategic goals.
-
-They evaluate the pros and cons of various technologies, frameworks, and platforms, considering
-factors such as ease of use, community support, vendor reliability, and compatibility with their
-specific use cases. The goal is to choose a data stack that aligns with the organization's needs,
-enables efficient data processing and analysis, promotes data governance and security, and empowers
-teams to deliver valuable insights and solutions.
-
-## What does a senior architect or engineer consider when choosing a tech stack?
-
-- Company Goals and Strategy.
-- Cost and Return on Investment (ROI).
-- Staffing and Skills.
-- Employee Happiness and Productivity.
-- Maintainability and Long-term Support.
-- Integration with Existing Systems.
-- Scalability and Performance.
-- Data Security and Compliance.
-- Vendor Reliability and Ecosystem.
-
-## What makes dlt a must-have for your data stack or platform?
-
-For starters, `dlt` is the first data pipeline solution that is built for your data team's ROI. Our
-vision is to add value, not gatekeep it.
-
-By being a library built to enable free usage, we are uniquely positioned to run in existing stacks
-without replacing them. This enables us to disrupt and revolutionise the industry in ways that only
-open source communities can.
-
-## dlt massively reduces pipeline maintenance, increases efficiency and ROI
-
-- Reduce engineering effort as much as 5x via a paradigm shift. Structure data automatically to not
-  do it manually.
-  Read about [structured data lake](https://dlthub.com/docs/blog/next-generation-data-platform), and
-  [how to do schema evolution](../reference/explainers/schema-evolution.md).
-- Better Collaboration and Communication: Structured data promotes better collaboration and
-  communication among team members. Since everyone operates on a shared understanding of the data
-  structure, it becomes easier to discuss and align on data-related topics. Queries, reports, and
-  analysis can be easily shared and understood by others, enhancing collaboration and teamwork.
-- Faster time to build pipelines: After extracting data, if you pass it to `dlt`, you are done. If
-  not, it needs to be structured. Because structuring is hard, we curate it. Curation involves at
-  least the producer, and consumer, but often also an analyst and the engineer, and is a long,
-  friction-ful process.
-- Usage focus improves ROI: To use data, we need to understand what it is. Structured data already
-  contains a technical description, accelerating usage.
-- Lower cost: Reading structured data is cheaper and faster because we can specify which parts of a
-  document we want to read.
-- Removing friction: By alerting schema changes to the producer and stakeholder, and by automating
-  structuring, we can keep the data engineer out of curation and remove the bottleneck.
-  [Notify maintenance events.](../running-in-production/running#inspect-save-and-alert-on-schema-changes)
-- Improving quality: No more garbage in, garbage out. Because `dlt` structures data and alerts schema
-  changes, we can have better governance.
-
-## dlt makes your team happy
-
-- Spend more time using data, less time loading it. When you build a `dlt` pipeline, you only build
-  the extraction part, automating the tedious structuring and loading.
-- Data meshing to reduce friction: By structuring data before loading, the engineer is no longer
-  involved in curation. This makes both the engineer and the others happy.
-- Better governance with end to end pipelining via dbt:
-  [run dbt packages on the fly](../dlt-ecosystem/transformations/dbt.md),
-  [lineage out of the box](../dlt-ecosystem/visualizations/understanding-the-tables).
-- Zero learning curve: Declarative loading, simple functional programming. By using `dlt`'s
-  declarative, standard approach to loading data, there is no complicated code to maintain, and the
-  analysts can thus maintain the code.
-- Autonomy and Self service: Customising pipelines is easy, whether you want to plug an anonymiser,
-  rename things, or curate what you load.
-  [Anonymisers, renamers](../general-usage/customising-pipelines/pseudonymizing_columns.md).
-- Easy discovery and governance: By tracking metadata like data lineage, describing data with
-  schemas, and alerting changes, we stay on top of the data.
-- Simplified access: Querying structured data can be done by anyone with their tools of choice.
-
-## dlt is a library that you can run in unprecedented places
-
-Before `dlt` existed, all loading tools were built either
-
-- as SaaS (5tran, Stitch, etc.);
-- as installed apps with their own orchestrator: Pentaho, Talend, Airbyte;
-- or as abandonware framework meant to be unrunnable without help (Singer was released without
-  orchestration, not for public).
-
-`dlt` is the first python library in this space, which means you can just run it wherever the rest of
-your python stuff runs, without adding complexity.
-
-- You can run `dlt` in [Airflow](../dlt-ecosystem/deployments/orchestrators/airflow-deployment.md) -
-  this is the first ingestion tool that does this.
-- You can run `dlt` in small spaces like [Cloud Functions](../dlt-ecosystem/deployments/running-in-cloud-functions.md)
-  or [GitHub Actions](../dlt-ecosystem/deployments/orchestrators/github-actions.md) -
-  so you could easily set up webhooks, etc.
-- You can run `dlt` in your Jupyter Notebook and load data to [DuckDB](../dlt-ecosystem/destinations/duckdb.md).
-- You can run `dlt` on large machines, it will attempt to make the best use of the resources available
-  to it.
-- You can [run `dlt` locally](../walkthroughs/run-a-pipeline.md) just like you run any python scripts.
-
-The implications:
-
-- Empowering Data Teams and Collaboration: You can discover or prototype in notebooks, run in cloud
-  functions, and deploy to production, the same scalable, robust code. No more friction between
-  roles.
-  [Colab demo.](https://colab.research.google.com/drive/1NfSB1DpwbbHX9_t5vlalBTf13utwpMGx?usp=sharing#scrollTo=A3NRS0y38alk)
-- Rapid Data Exploration and Prototyping: By running in Colab with DuckDB, you can explore
-  semi-structured data much faster by structuring it with `dlt` and analysing it in SQL.
-  [Schema inference](../general-usage/schema#data-normalizer),
-  [exploring the loaded data](../dlt-ecosystem/visualizations/understanding-the-tables#show-tables-and-data-in-the-destination).
-- No vendor limits: `dlt` is forever free, with no vendor strings. We do not create value by creating
-  a pain for you and solving it. We create value by supporting you beyond.
-- `dlt` removes complexity: You can use `dlt` in your existing stack, no overheads, no race conditions,
-  full observability. Other tools add complexity.
-- `dlt` can be leveraged by AI: Because it's a library with low complexity to use, large language
-  models can produce `dlt` code for your pipelines.
-- Ease of adoption: If you are running python, you can adopt `dlt`. `dlt` is orchestrator and
-  destination agnostic.
diff --git a/docs/website/docs/user-guides/images/colab-demo.png b/docs/website/docs/user-guides/images/colab-demo.png
deleted file mode 100644
index 4890e088ed..0000000000
Binary files a/docs/website/docs/user-guides/images/colab-demo.png and /dev/null differ
diff --git a/docs/website/docs/user-guides/images/dlt-main.png b/docs/website/docs/user-guides/images/dlt-main.png
deleted file mode 100644
index 8ddfdfbf13..0000000000
Binary files a/docs/website/docs/user-guides/images/dlt-main.png and /dev/null differ
diff --git a/docs/website/docs/user-guides/images/structured-data.png b/docs/website/docs/user-guides/images/structured-data.png
deleted file mode 100644
index 35057dbbf5..0000000000
Binary files a/docs/website/docs/user-guides/images/structured-data.png and /dev/null differ
diff --git a/docs/website/docs/walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer.md b/docs/website/docs/walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer.md
index d9e941b946..481eeeb674 100644
--- a/docs/website/docs/walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer.md
+++ b/docs/website/docs/walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer.md
@@ -390,7 +390,7 @@ There are two ways to pass the credentials
 ### 5. Configure `build/cloudbuild.yaml` to run it with Google Cloud Platform \[[Cloud Composer](https://console.cloud.google.com/composer/environments)\]
 
 - Read our doc
-  [How to deploy the main branch of your airflow project from GitHub to Cloud Composer](../../reference/airflow-gcp-cloud-composer.md).
+  [How to deploy the main branch of your airflow project from GitHub to Cloud Composer](../../reference/explainers/airflow-gcp-cloud-composer.md).
 
   There you can find:
 
diff --git a/docs/website/package-lock.json b/docs/website/package-lock.json
index 1a78d94e1b..ecbfdcc72f 100644
--- a/docs/website/package-lock.json
+++ b/docs/website/package-lock.json
@@ -1,11 +1,11 @@
 {
-  "name": "dltDocs",
+  "name": "dlt-docs",
   "version": "0.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "dltDocs",
+      "name": "dlt-docs",
       "version": "0.0.0",
       "dependencies": {
         "@docusaurus/core": "2.4.1",
diff --git a/docs/website/sidebars.js b/docs/website/sidebars.js
index 4b7aa65c26..e25f8d8836 100644
--- a/docs/website/sidebars.js
+++ b/docs/website/sidebars.js
@@ -99,24 +99,14 @@ const sidebars = {
           type: 'category',
           label: 'Deployments',
           link: {
-            type: 'generated-index',
-            title: 'Deployments',
-            description: 'Overview over where you can deploy dlt.',
-            slug: 'dlt-ecosystem/deployments',
-            keywords: ['deployments'],
+            type: 'doc',
+            id: 'dlt-ecosystem/deployments/index',
           },
           items: [
-            'dlt-ecosystem/deployments/where-can-dlt-run',
-            'dlt-ecosystem/deployments/running-in-cloud-functions',
-            {
-              type: 'category',
-              label: 'Orchestrators',
-              items: [
-                'dlt-ecosystem/deployments/orchestrators/choosing-an-orchestrator',
-                'dlt-ecosystem/deployments/orchestrators/airflow-deployment',
-                'dlt-ecosystem/deployments/orchestrators/github-actions',
-              ]
-            },
+            'walkthroughs/deploy-a-pipeline/deploy-with-github-actions',
+            'walkthroughs/deploy-a-pipeline/deploy-with-airflow-composer',
+            'walkthroughs/deploy-a-pipeline/deploy-with-google-cloud-functions',
+            'walkthroughs/deploy-a-pipeline/deploy-gcp-cloud-function-as-webhook',
           ]
         },
         {
@@ -146,23 +136,6 @@ const sidebars = {
         },
       ],
     },
-    {
-      type: 'category',
-      label: 'User Guides',
-      link: {
-        type: 'generated-index',
-        title: 'User Guides',
-        slug: 'user-guides',
-        keywords: ['user guides'],
-      },
-      items: [
-        'user-guides/analytics-engineer',
-        'user-guides/data-beginner',
-        'user-guides/data-engineer',
-        'user-guides/data-scientist',
-        'user-guides/engineering-manager',
-      ],
-    },
     {
       type: 'category',
       label: 'Walkthroughs',
@@ -208,8 +181,6 @@ const sidebars = {
         keywords: ['general usage'],
       },
       items: [
-        'general-usage/glossary',
-        'general-usage/import-dlt',
         'general-usage/resource',
         'general-usage/source',
         'general-usage/pipeline',
@@ -219,6 +190,7 @@ const sidebars = {
         'general-usage/credentials',
         'general-usage/schema',
         'general-usage/configuration',
+        'general-usage/glossary',
         {
           type: 'category',
           label: 'Customising pipelines',
@@ -260,10 +232,9 @@ const sidebars = {
         'reference/installation',
         'reference/command-line-interface',
         'reference/performance',
-        'reference/explainers/how-dlt-works',
-        'reference/explainers/schema-evolution',
         'reference/telemetry',
-        'reference/airflow-gcp-cloud-composer',
+        'reference/explainers/how-dlt-works',
+        'reference/explainers/airflow-gcp-cloud-composer',
       ],
     },
   ]
diff --git a/docs/website/src/css/custom.css b/docs/website/src/css/custom.css
index 7ea5b73cc6..9351897c4e 100644
--- a/docs/website/src/css/custom.css
+++ b/docs/website/src/css/custom.css
@@ -49,16 +49,16 @@
   --ifm-background-color: #F7F9FC;
   --ifm-color-primary: #4C4898;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
-  --ifm-font-color-base: #f3ff36;
+  --ifm-font-color-base: #F7F9FC;
   --ifm-gradient: transparent;
   --ifm-menu-color: #FFFFFF;
   --ifm-menu-color-active: #f3ff36;
   --ifm-menu-color: #dadde1;
-  --ifm-heading-color: #f3ff36;
+  --ifm-heading-color: #F7F9FC;
   --docsearch-searchbox-background: #ffffff !important;
   --docsearch-text-color: #191937 !important;
   --docsearch-searchbox-focus-background: #ffffff !important;
-  --ifm-color-content-secondary: #f3ff36 !important;
+  --ifm-color-content-secondary: #F7F9FC !important;
   --ifm-pagination-nav-color-hover: #f3ff36;
   --ifm-navbar-link-color:#ffffff;
   --ifm-navbar-link-hover-color:#f3ff36;
@@ -592,103 +592,83 @@ html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(4)>div>[
   background-image: url(../../static/img/UsingLoadedData-Active-1.svg);
 }
 
-/* User guides */
+/* walkthrough */
 
 .theme-doc-sidebar-menu.menu__list>li:nth-child(5)>div>a::before {
-  background-image: url(../../static/img/UserGuide-Inactive.svg);
+  background-image: url(../../static/img/Walkthrough-Inactive.svg);
 }
 
 .theme-doc-sidebar-menu.menu__list>li:hover:nth-child(5)>div>a::before,
-.theme-doc-sidebar-menu.menu__list>li:nth-child(5)>div>[aria-expanded="true"]::before {
-  background-image: url(../../static/img/UserGuide-Active.svg);
+.theme-doc-sidebar-menu.menu__list>li:nth-child(6)>div>[aria-expanded="true"]::before {
+  background-image: url(../../static/img/Walkthrough-Active.svg);
 }
 
 html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(5)>div>a::before {
-  background-image: url(../../static/img/UserGuide-Inactive-1.svg);
+  background-image: url(../../static/img/Walkthrough-Inactive-1.svg);
 }
 
 html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:hover:nth-child(5)>div>a::before,
 html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(5)>div>[aria-expanded="true"]::before {
-  background-image: url(../../static/img/UserGuide-Active-1.svg);
+  background-image: url(../../static/img/Walkthrough-Active-1.svg);
 }
 
-/* walkthrough */
+/* general usage */
 
 .theme-doc-sidebar-menu.menu__list>li:nth-child(6)>div>a::before {
-  background-image: url(../../static/img/Walkthrough-Inactive.svg);
+  background-image: url(../../static/img/GeneralUsage-Inactive.svg);
 }
 
 .theme-doc-sidebar-menu.menu__list>li:hover:nth-child(6)>div>a::before,
 .theme-doc-sidebar-menu.menu__list>li:nth-child(6)>div>[aria-expanded="true"]::before {
-  background-image: url(../../static/img/Walkthrough-Active.svg);
+  background-image: url(../../static/img/GeneralUsage-Active.svg);
 }
 
 html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(6)>div>a::before {
-  background-image: url(../../static/img/Walkthrough-Inactive-1.svg);
+  background-image: url(../../static/img/GeneralUsage-Inactive-1.svg);
 }
 
 html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:hover:nth-child(6)>div>a::before,
 html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(6)>div>[aria-expanded="true"]::before {
-  background-image: url(../../static/img/Walkthrough-Active-1.svg);
+  background-image: url(../../static/img/GeneralUsage-Active-1.svg);
 }
 
-/* general usage */
+/*  Running in production */
 
 .theme-doc-sidebar-menu.menu__list>li:nth-child(7)>div>a::before {
-  background-image: url(../../static/img/GeneralUsage-Inactive.svg);
+  background-image: url(../../static/img/RunningInProduction-Inactive.svg);
 }
 
 .theme-doc-sidebar-menu.menu__list>li:hover:nth-child(7)>div>a::before,
 .theme-doc-sidebar-menu.menu__list>li:nth-child(7)>div>[aria-expanded="true"]::before {
-  background-image: url(../../static/img/GeneralUsage-Active.svg);
+  background-image: url(../../static/img/RunningInProduction-Active.svg);
 }
 
 html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(7)>div>a::before {
-  background-image: url(../../static/img/GeneralUsage-Inactive-1.svg);
+  background-image: url(../../static/img/RunningInProduction-Inactive-1.svg);
 }
 
 html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:hover:nth-child(7)>div>a::before,
 html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(7)>div>[aria-expanded="true"]::before {
-  background-image: url(../../static/img/GeneralUsage-Active-1.svg);
-}
-
-/*  Running in production */
-
-.theme-doc-sidebar-menu.menu__list>li:nth-child(8)>div>a::before {
-  background-image: url(../../static/img/RunningInProduction-Inactive.svg);
-}
-
-.theme-doc-sidebar-menu.menu__list>li:hover:nth-child(8)>div>a::before,
-.theme-doc-sidebar-menu.menu__list>li:nth-child(8)>div>[aria-expanded="true"]::before {
-  background-image: url(../../static/img/RunningInProduction-Active.svg);
-}
-
-html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(8)>div>a::before {
-  background-image: url(../../static/img/RunningInProduction-Inactive-1.svg);
-}
-
-html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:hover:nth-child(8)>div>a::before,
-html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(8)>div>[aria-expanded="true"]::before {
   background-image: url(../../static/img/RunningInProduction-Active-1.svg);
 }
 
 /* Reference */
 
-.theme-doc-sidebar-menu.menu__list>li:nth-child(9)>div>a::before {
+.theme-doc-sidebar-menu.menu__list>li:nth-child(8)>div>a::before {
   background-image: url(../../static/img/Reference-Inactive.svg);
 }
 
-.theme-doc-sidebar-menu.menu__list>li:hover:nth-child(9)>div>a::before,
+.theme-doc-sidebar-menu.menu__list>li:hover:nth-child(8)>div>a::before,
 .theme-doc-sidebar-menu.menu__list>li:nth-child(9)>div>[aria-expanded="true"]::before {
   background-image: url(../../static/img/Reference-Active.svg);
 }
 
-html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(9)>div>a::before {
+html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(8)>div>a::before {
   background-image: url(../../static/img/Reference-Inactive-1.svg);
 }
 
-html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:hover:nth-child(9)>div>a::before,
-html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(9)>div>[aria-expanded="true"]::before {
+html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:hover:nth-child(8)>div>a::before,
+html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(8)>div>[aria-expanded="true"]::before {
   background-image: url(../../static/img/Reference-Active-1.svg);
 }
 
@@ -719,7 +699,7 @@ html[data-theme='dark'] .theme-doc-sidebar-menu.menu__list>li:nth-child(9)>div>[
     display: table;
     background: var(--ifm-color-primary) !important;
     padding-bottom: 4px!important;
-  } 
+  }
 
   .menu__link.slack-navbar:before,
   .menu__link.github-navbar:before {