clarify some sections

tobiasraabe · tobiasraabe · commit 3aa4cef51ca9 · 2026-05-01T10:53:50.000+02:00
diff --git a/docs/source/how_to_guides/index.md b/docs/source/how_to_guides/index.md
@@ -10,7 +10,7 @@ specific tasks with pytask.
 - [Migrating From Scripts To Pytask](migrating_from_scripts_to_pytask.md)
 - [Interfaces For Dependencies Products](interfaces_for_dependencies_products.md)
 - [Move a Project to Another Machine](move_project_to_another_machine.md)
-- [Update the Lockfile to Match Project State](reconciling_lockfile_state.md)
+- [Update the Lockfile to Match Project State](update_the_lockfile_to_match_project_state.md)
 - [Remote Files](remote_files.md)
 - [Functional Interface](functional_interface.md)
 - [Capture Warnings](capture_warnings.md)
diff --git a/docs/source/how_to_guides/update_the_lockfile_to_match_project_state.md b/docs/source/how_to_guides/update_the_lockfile_to_match_project_state.md
diff --git a/docs/source/tutorials/set_up_a_project.md b/docs/source/tutorials/set_up_a_project.md
@@ -133,22 +133,24 @@ The `[tool.pytask.ini_options]` section tells pytask to look for tasks in
 `src/my_project`. You will learn more about configuration in the
 [configuration tutorial](configuration.md).
 
-## The `.pytask` directory
-
-The `.pytask` directory is where pytask stores its information. You do not need to
-interact with it.
-
 ## The `pytask.lock` file
 
 The `pytask.lock` file records which tasks and products are up to date. pytask updates
 it during builds so later runs can skip unchanged tasks. This file should be kept in
 version control.
 
-When you move a project to another machine, see
-[Move a Project to Another Machine](../how_to_guides/move_project_to_another_machine.md).
-To update recorded task state manually, use
-[`pytask lock`](../reference_guides/commands.md#pytask-lock). For details on what pytask
-stores in the file, see [Lockfile](../reference_guides/lockfile.md).
+!!! seealso
+
+    You will later learn how to sync the state of the lockfile with the project state with
+    the [`pytask lock`](../reference_guides/commands.md#pytask-lock) command or how the
+    lockfile enables you to
+    [move a project to another machine](../how_to_guides/move_project_to_another_machine.md),
+    but don't worry about it for now.
+
+## The `.pytask` directory
+
+The `.pytask` directory is where pytask stores some of its ephemeral information. You do
+not need to interact with it, nor do you need to keep it in version control.
 
 ## Installation
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -38,7 +38,7 @@ nav:
       - Migrating From Scripts To pytask: how_to_guides/migrating_from_scripts_to_pytask.md
       - Interfaces For Dependencies And Products: how_to_guides/interfaces_for_dependencies_products.md
       - Move a Project to Another Machine: how_to_guides/move_project_to_another_machine.md
-      - Reconciling Lockfile State: how_to_guides/reconciling_lockfile_state.md
+      - Update the Lockfile to Match Project State: how_to_guides/update_the_lockfile_to_match_project_state.md
       - Remote Files: how_to_guides/remote_files.md
       - Functional Interface: how_to_guides/functional_interface.md
       - Capture Warnings: how_to_guides/capture_warnings.md
