adjust docs.

Author: tobiasraabe

docs/source/how_to_guides/portability.md

@@ -8,21 +8,6 @@ The lockfile format and behavior are documented in the
 [reference guide](../reference_guides/lockfile.md).
 ```
 
-## What makes a project portable
-
-There are two things that must stay stable across machines:
-
-First, task and node IDs must be stable. An ID is the unique identifier that ties a task
-or node to an entry in `pytask.lock`. pytask builds these IDs from project-relative
-paths anchored at the project root, so most users do not need to do anything. If you
-implement custom nodes, make sure their IDs remain project-relative and stable across
-machines.
-
-Second, state values must be portable. The lockfile stores opaque state strings from
-`PNode.state()` and `PTask.state()`, and pytask uses them to decide whether a task is up
-to date. Content hashes are portable; timestamps or absolute paths are not. This mostly
-matters when you define custom nodes or custom hash functions.
-
 ## How to port a project
 
 Use this checklist when you move a project to another machine or environment.
@@ -36,37 +21,45 @@ Use this checklist when you move a project to another machine or environment.
    ```
 
    If you already have a recent lockfile and up-to-date outputs, you can skip this step.
-   If the lockfile has stale entries, clean it first:
-
-   ```console
-   $ pytask build --clean-lockfile
-   ```
 
 1. **Ship the right files.**
 
    Commit `pytask.lock` to your repository and move it with the project. In practice,
    you should move:
 
-   - the project files tracked in version control (source, configuration, data inputs)
-   - `pytask.lock`
+   - the project files tracked in version control (source, configuration, data inputs
+     and `pytask.lock`)
    - the build artifacts you want to reuse (often in `bld/` if you follow the tutorial
      layout)
+   - the `.pytask` folder in case you are using the data catalog and it manages some of
+     the files
 
-   The lockfile does not contain the artifacts themselves. If you move only the lockfile
-   but not the outputs, pytask will re-run tasks because output states will not match.
-
-1. **Preserve relative paths.**
+1. **Files outside the project**
 
-   IDs are project-relative. If your dependencies or products live outside the project
-   root, their IDs include `..` segments. Make sure the same relative layout exists on
-   the target machine, or update the paths and run `pytask build` once to refresh
-   `pytask.lock`.
+   If you have files outside the project root (the folder with the `pyproject.toml`
+   file), you need to make sure that the same relative layout exists on the target
+   machine.
 
 1. **Run pytask on the target machine.**
 
    When states match, tasks are skipped. When they differ, tasks run and the lockfile is
    updated.
 
+## What makes a project portable
+
+There are two things that must stay stable across machines:
+
+First, task and node IDs must be stable. An ID is the unique identifier that ties a task
+or node to an entry in `pytask.lock`. pytask builds these IDs from project-relative
+paths anchored at the project root, so most users do not need to do anything. If you
+implement custom nodes, make sure their IDs remain project-relative and stable across
+machines.
+
+Second, state values must be portable. The lockfile stores opaque state strings from
+`PNode.state()` and `PTask.state()`, and pytask uses them to decide whether a task is up
+to date. Content hashes are portable; timestamps or absolute paths are not. This mostly
+matters when you define custom nodes or custom hash functions.
+
 ## Tips for stable state values
 
 - Prefer file content hashes over timestamps for custom nodes.