Refine docs.

Author: tobiasraabe

docs/source/how_to_guides/bp_structure_of_a_research_project.md

@@ -23,6 +23,10 @@ As an example, look at two repositories from a COVID-19 forecasting project.
 - [sid](https://github.com/covid-19-impact-lab/sid) contains the code for the
   epidemiological model which is applied in the research project.
 
+```{seealso}
+Consider using [workspaces](using_workspaces.md) which instead of separate repositories.
+```
+
 Separating the model code from the research project provided several benefits.
 
 - The model code is isolated and has its own test suite. Assessing and ensuring the code

docs/source/how_to_guides/index.md

@@ -23,6 +23,7 @@ provisional_nodes_and_task_generators
 writing_custom_nodes
 extending_pytask
 the_data_catalog
+using_workspaces
 ```
 
 ## Best Practice Guides

docs/source/how_to_guides/using_workspaces.md

@@ -0,0 +1,51 @@
+# Using workspaces
+
+There are situations where you want to structure your project as a multi-package
+workspace. Reasons are
+
+- You are developing a scientific package alongside the project that you want to publish
+  later.
+- The code for dealing with the dataset should be reused in other projects.
+- You want to strictly separate the pytask tasks from the remaining code to be able to
+  switch to another build system.
+
+In those instances, a workspace might be the right choice.
+
+```text
+project
+├── packages
+│   ├── data
+│   │   ├── pyproject.toml
+│   │   └── src
+│   │       └── data
+│   │           ├── __init__.py
+│   │           └── ...
+│   ├── analysis
+│   │   ├── pyproject.toml
+│   │   └── src
+│   │       └── analysis
+│   │           ├── __init__.py
+│   │           └── ...
+│   └── tasks
+│       ├── pyproject.toml
+│       └── src
+│           └── tasks
+│               ├── __init__.py
+│               └── ...
+│
+├── pyproject.toml
+├── README.md
+├── ...
+```
+
+## Using workspaces with uv
+
+uv provides excellent support for workspaces which you can read more about in the
+[uv documentation](https://docs.astral.sh/uv/concepts/projects/workspaces).
+
+## Using workspaces with pixi
+
+pixi is still working on a native workspace experience, but there are workarounds.
+
+- https://github.com/prefix-dev/pixi/discussions/387
+- https://github.com/Andre-Medina/python-pixi-mono-template

docs/source/tutorials/set_up_a_project.md

@@ -6,6 +6,12 @@ tutorial explains the minimal setup.
 If you want to use pytask with a collection of scripts, you can skip this lesson and
 move to the next section of the tutorials.
 
+```{seealso}
+In case you are thinking about developing multiple packages in the project that should be separated (one for dealing with the data, one for the analysis and a package for the pytask tasks), consider using a [workspace](../how_to_guides/using_workspaces.md).
+```
+
+## The directory structure
+
 The following directory tree gives an overview of the project's different parts.
 
 ```text
@@ -93,10 +99,6 @@ paths = ["src/my_project"]
 
 uv automatically handles build system configuration and package discovery.
 
-```{seealso}
-Another benefit of using uv is that it makes it easy handling repositories with multiple packages allowing you to separate the package with tasks from your potential scientific package. Read more about [workspaces in the uv documentation](https://docs.astral.sh/uv/concepts/projects/workspaces/).
-```
-
 ````
 
 ````{tab-item} pixi