docs: fix explanation pages

docs/common/craft-parts/explanation/how_parts_are_built.rst

@@ -33,6 +33,12 @@ number of subdirectories:
 The standard actions for the *pull* step can be overridden or extended by
 using the :ref:`override_pull` key to describe a series of actions.
 
+The overlay step
+~~~~~~~~~~~~~~~~
+
+The *overlay* step is used in some Craft tools to provide an additional layer that
+overlays the base filesystem layer. Check :ref:`Overlay step explanation <overlays>` for more details.
+
 The build step
 ~~~~~~~~~~~~~~
 

docs/common/craft-parts/explanation/overlay_parameters.rst

@@ -4,13 +4,13 @@ Overlay Parameters
 ------------------
 
 A part has three parameters that can be used to adjust how the overlay step
-works: ``overlay-packages``, ``overlay-script`` and ``overlay-filter``.
+works: ``overlay-packages``, ``overlay-script`` and ``overlay``.
 ``overlay-packages`` and ``overlay`` (the filter parameter) behave much the
 same way as the related parameters on the ``STAGE`` step. ``overlay-script``
 likewise behaves similarly to ``override-stage``, including having access to
 the ``craftctl`` command.
 
-An example parts section with overlay parameters looks as follows:
+An example of a parts section with overlay parameters looks as follows:
 
 .. code-block:: yaml
 

docs/common/craft-parts/explanation/overlays.rst

@@ -1,6 +1,8 @@
-****************
-``OVERLAY`` Step
-****************
+.. _overlays:
+
+************
+OVERLAY Step
+************
 
 Some Craft applications, such as Rockcraft_, include entire base filesystems in
 addition to the usual part-generated payload. The ``OVERLAY`` step provides the
@@ -146,10 +148,6 @@ for the part will re-run. If the :ref:`overlay is visible <overlay_visibility>`
 to a part, the overlay integrity code is added to future steps of the part,
 ensuring proper invalidation of those steps if overlay data changes.
 
-Step Invalidation
-=================
-
-
 
 .. _OCI image layer specification: https://github.com/opencontainers/image-spec/blob/master/layer.md
 .. _Rockcraft: https://canonical-rockcraft.readthedocs-hosted.com/

docs/common/craft-parts/explanation/parts.rst

@@ -9,18 +9,8 @@ part of a larger project containing many components.
 
 When the Craft Parts framework is used to process a part on behalf of a tool
 or library, it performs some or all of the steps described in the
-:ref:`parts lifecycle <lifecycle>`:
-
-#. The *pull* step pulls the source code and dependencies from locations
-   defined in the part and places them into a package cache.
-#. The *overlay* step unpacks them into a base file system chosen from a
-   collection of standard file system images.
-#. The *build* step runs a suitable build tool for the sources to compile
-   a set of build products or artefacts.
-#. The *stage* step copies the build products for the part into a common
-   area for all parts in a project.
-#. The *prime* step copies the files to be deployed into an area for
-   further processing.
+:ref:`parts lifecycle <lifecycle>`: *PULL*, *OVERLAY*, *BUILD*, *STAGE* and
+*PRIME*.
 
 Not all of these steps may be needed for every use case, and tools that use
 the Craft Parts framework can skip those that are not appropriate for their
@@ -91,6 +81,8 @@ sources where builds will occur. **Note:** This property restricts the build
 to the subdirectory specified, preventing access to files in the parent
 directory and elsewhere in the file system directory structure.
 
+.. _build_dependencies:
+
 Build dependencies
 ~~~~~~~~~~~~~~~~~~
 
@@ -149,6 +141,8 @@ The result of the *build* step is a set of build artefacts or products that
 are the same as those that would be produced by manually compiling or
 building the software.
 
+.. _build_artefacts:
+
 Build artefacts
 ~~~~~~~~~~~~~~~
 
@@ -165,12 +159,18 @@ system packages that need to be deployed with the part are specified using
 the :ref:`stage_snaps` and :ref:`stage_packages` properties. Files to be
 deployed are specified using the :ref:`stage` property.
 
+.. ifconfig:: project in ("Rockcraft",)
+
+   Chisel slices can be specified in :ref:`stage_packages` property as well, but
+   they are mutually exclusive to use with deb system packages. 
+
 In the final *prime* step, the files needed for deployment are copied from
 the staging area to the priming area. During this step the ``prime`` property
 is typically used to exclude files in the staging area that are not required
 at run-time. This is especially useful for multi-part projects that include
 their own compilers or development tools.
 
+
 .. _parts_build-order:
 
 Defining the build order

docs/common/craft-parts/reference/part_properties.rst

@@ -69,7 +69,10 @@ build-snaps
 
 The snaps to be installed in the build environment before the build is
 performed. These provide libraries and executables that the part needs during
-the build process.
+the build process. They take the form of ``<snap>/<version>/<channel>``,
+``<snap>/<channel>`` or just ``<snap>``. For example, the ``juju`` snap could be
+specified as ``juju/2.9/stable``, ``juju/latest/stable`` or ``juju/stable`` to
+select different versions.
 
 .. _organize:
 

docs/explanation/index.rst

@@ -3,6 +3,9 @@
 Explanation
 ***********
 
+This section of the documentation covers the concepts of Craft Parts, how they
+can be used, and the lifecycle of the different steps performed on them.
+
 .. toctree::
    :maxdepth: 1