diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst
index e10c47b5a7ca..648b7aa09137 100644
--- a/docs/devel/testing.rst
+++ b/docs/devel/testing.rst
@@ -429,49 +429,57 @@ using the ``lcitool`` program provided by the ``libvirt-ci`` project:
 
   https://gitlab.com/libvirt/libvirt-ci
 
-In that project, there is a ``mappings.yml`` file defining the distro native
-package names for a wide variety of third party projects. This is processed
-in combination with a project defined list of build pre-requisites to determine
-the list of native packages to install on each distribution. This can be used
-to generate dockerfiles, VM package lists and Cirrus CI variables needed to
-setup build environments across OS distributions with a consistent set of
-packages present.
-
-When preparing a patch series that adds a new build pre-requisite to QEMU,
-updates to various lcitool data files may be required.
+``libvirt-ci`` contains an ``lcitool`` program as well as a list of
+mappings to distribution package names for a wide variety of third
+party projects.  ``lcitool`` applies the mappings to a list of build
+pre-requisites in ``tests/lcitool/projects/qemu.yml``, determines the
+list of native packages to install on each distribution, and uses them
+to generate build environments (dockerfiles and Cirrus CI variable files)
+that are consistent across OS distribution.
 
 
 Adding new build pre-requisites
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+When preparing a patch series that adds a new build
+pre-requisite to QEMU, the prerequisites should to be added to
+``tests/lcitool/projects/qemu.yml`` in order to make the dependency
+available in the CI build environments.
+
 In the simple case where the pre-requisite is already known to ``libvirt-ci``
-the following steps are needed
+the following steps are needed:
 
  * Edit ``tests/lcitool/projects/qemu.yml`` and add the pre-requisite
 
  * Run ``make lcitool-refresh`` to re-generate all relevant build environment
    manifests
 
-In some cases ``libvirt-ci`` will not know about the build pre-requisite and
-thus some extra preparation steps will be required first
+In some cases ``libvirt-ci`` will not know about the build
+pre-requisite and thus some extra preparation steps will be required
+first.  Even though you can add the mappings for testing purposes to
+``tests/lcitool/mappings.yml`` in the QEMU repository, please contribute
+the mapping to the ``libvirt-ci`` project as well:
 
  * Fork the ``libvirt-ci`` project on gitlab
 
- * Edit the ``mappings.yml`` change to add an entry for the new build
-   prerequisite, listing its native package name on as many OS distros
-   as practical.
+ * Add an entry for the new build prerequisite to
+   ``lcitool/facts/mappings.yml``, listing its native package name on as
+   many OS distros as practical.  Run ``python -m pytest --regenerate-output``
+   and check that the changes are correct.
 
- * Commit the ``mappings.yml`` change and submit a merge request to
-   the ``libvirt-ci`` project, noting in the description that this
-   is a new build pre-requisite desired for use with QEMU
+ * Commit the ``mappings.yml`` change together with the regenerated test
+   files, and submit a merge request to the ``libvirt-ci`` project.
+   Please note in the description that this is a new build pre-requisite
+   desired for use with QEMU
 
  * CI pipeline will run to validate that the changes to ``mappings.yml``
    are correct, by attempting to install the newly listed package on
    all OS distributions supported by ``libvirt-ci``.
 
  * Once the merge request is accepted, go back to QEMU and update
-   the ``libvirt-ci`` submodule to point to a commit that contains
-   the ``mappings.yml`` update.
+   the ``tests/lcitool/libvirt-ci`` submodule to point to a commit that
+   contains the ``mappings.yml`` update.  Then add the prerequisite and
+   run ``make lcitool-refresh``.
 
 
 Adding new OS distros
@@ -498,18 +506,20 @@ Assuming there is agreement to add a new OS distro then
 
  * Fork the ``libvirt-ci`` project on gitlab
 
- * Add metadata under ``guests/lcitool/lcitool/ansible/group_vars/``
-   for the new OS distro. There might be code changes required if
-   the OS distro uses a package format not currently known. The
-   ``libvirt-ci`` maintainers can advise on this when the issue
-   is file.
+ * Add metadata under ``lcitool/facts/targets/`` for the new OS
+   distro. There might be code changes required if the OS distro
+   uses a package format not currently known. The ``libvirt-ci``
+   maintainers can advise on this when the issue is filed.
 
- * Edit the ``mappings.yml`` change to update all the existing package
-   entries, providing details of the new OS distro
+ * Edit the ``lcitool/facts/mappings.yml`` change to add entries for
+   the new OS, listing the native package names for as many packages
+   as practical.  Run ``python -m pytest --regenerate-output`` and
+   check that the changes are correct.
 
- * Commit the ``mappings.yml`` change and submit a merge request to
-   the ``libvirt-ci`` project, noting in the description that this
-   is a new build pre-requisite desired for use with QEMU
+ * Commit the changes to ``lcitool/facts`` and the regenerated test
+   files, and submit a merge request to the ``libvirt-ci`` project.
+   Please note in the description that this is a new build pre-requisite
+   desired for use with QEMU
 
  * CI pipeline will run to validate that the changes to ``mappings.yml``
    are correct, by attempting to install the newly listed package on
