From ce813ffcce63458ffc14f594847418871184e35c Mon Sep 17 00:00:00 2001
From: Elias <110238618+ESadek-MO@users.noreply.github.com>
Date: Thu, 9 Nov 2023 14:29:27 +0000
Subject: [PATCH] Added xarray phrasebook doc page (#5564)

---
 docs/src/community/index.rst       |  2 +
 docs/src/community/iris_xarray.rst |  1 +
 docs/src/community/phrasebook.rst  | 66 ++++++++++++++++++++++++++++++
 docs/src/whatsnew/latest.rst       |  3 ++
 4 files changed, 72 insertions(+)
 create mode 100644 docs/src/community/phrasebook.rst

diff --git a/docs/src/community/index.rst b/docs/src/community/index.rst
index 114cb96fe9..ee227513b3 100644
--- a/docs/src/community/index.rst
+++ b/docs/src/community/index.rst
@@ -40,12 +40,14 @@ smoother interoperability:
 
 * The :mod:`iris.pandas` module
 * :doc:`iris_xarray`
+* :doc:`phrasebook`
 
 .. toctree::
    :maxdepth: 1
    :hidden:
 
    iris_xarray
+   phrasebook
 
 Plugins
 -------
diff --git a/docs/src/community/iris_xarray.rst b/docs/src/community/iris_xarray.rst
index 2250e3c0a3..9d795fcd9e 100644
--- a/docs/src/community/iris_xarray.rst
+++ b/docs/src/community/iris_xarray.rst
@@ -7,6 +7,7 @@ Iris ❤️ :term:`Xarray`
 There is a lot of overlap between Iris and :term:`Xarray`, but some important
 differences too. Below is a summary of the most important differences, so that
 you can be prepared, and to help you choose the best package for your use case.
+See :doc:`phrasebook` for a broad comparison of terminology.
 
 Overall Experience
 ------------------
diff --git a/docs/src/community/phrasebook.rst b/docs/src/community/phrasebook.rst
new file mode 100644
index 0000000000..bcd91cca83
--- /dev/null
+++ b/docs/src/community/phrasebook.rst
@@ -0,0 +1,66 @@
+.. include:: ../common_links.inc
+
+.. _phrasebook:
+
+Package Phrasebook
+===================
+
+There are a number of similar packages to Iris, and a lot of these have their own
+terminology for similar things. Whether you're coming or going, we hope this might
+be a helpful guide to these differences!
+Definitions for each can be found in :ref:`glossary`. See also
+`Xarray terminology <https://docs.xarray.dev/en/stable/user-guide/terminology.html>`_.
+
+.. list-table:: Phrasebook
+   :widths: 25 25 25 50
+   :header-rows: 1
+
+   * - Iris
+     - Xarray
+     - Example
+     - Notes
+   * - Non-Lazy
+     - Eager
+     -
+     - Used to relate to functions, rather than the data.
+   * - Cube
+     - DataArray
+     -
+     -
+   * - CubeList
+     - Dataset
+     -
+     - Though similar, a CubeList is a simpler object, and is
+       not a perfect comparison to a Dataset
+   * - Merge/ Concatenate
+     - Concatenate
+     - `Xarray concatenate <https://docs.xarray.dev/en/stable/user-guide/combining.html#concatenate>`_
+     - Xarray's concatenate has the capability to largely do what both
+       Iris merge and Iris concatenate do. However, this is not a perfect comparison,
+       please see the link for more information.
+   * -
+     - Merge
+     - `Xarray merge <https://docs.xarray.dev/en/stable/user-guide/combining.html#merge>`_
+     - Xarray's Merge function doesn't map neatly map to any Iris feature.
+       Please see the link for more information.
+   * - Scalar Coordinate
+     -
+     -
+     - Iris makes a distinction between scalar coordinates and non-scalar coordinates,
+       whereas xarray documentation makes a distinction between scalar and non-scalar *data*.
+       It is possible to make coordinates with scalar data in both Iris and xarray
+       but only Iris will label such coordinates.
+   * - AuxCoord
+     - Non-Dimensional Coordinate
+     -
+     - Coordinates in Iris and xarray are categorised using different rules,
+       and so are not a one-to-one match.
+   * - DimCoord
+     - Dimension Coordinate
+     -
+     - Coordinates in Iris and xarray are categorised using different rules,
+       and so are not a one-to-one match.
+
+----
+
+`To top <phrasebook_>`_
\ No newline at end of file
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
index 5aa87f6473..c4be2ab7d2 100644
--- a/docs/src/whatsnew/latest.rst
+++ b/docs/src/whatsnew/latest.rst
@@ -93,6 +93,9 @@ This document explains the changes made to Iris for this release
 
 #. `@tkknight`_  removed broken git links. (:pull:`5569`)
 
+#. `@ESadek-MO`_ added a phrasebook for synonymous terms used in similar
+   packages. (:pull:`5564`)
+
 
 💼 Internal
 ===========