diff --git a/source/_static/guide_issue.png b/source/_static/guide_issue.png
new file mode 100644
index 0000000000000000000000000000000000000000..7474c1816d02132284be98233d30d3018e419daa
Binary files /dev/null and b/source/_static/guide_issue.png differ
diff --git a/source/_static/guide_issue2.png b/source/_static/guide_issue2.png
new file mode 100644
index 0000000000000000000000000000000000000000..43bf6e0b9570801eefb69edaae64a079ab9d40b6
Binary files /dev/null and b/source/_static/guide_issue2.png differ
diff --git a/source/_static/guide_merge_request.png b/source/_static/guide_merge_request.png
new file mode 100644
index 0000000000000000000000000000000000000000..b01378c4f5a97ea948235c766f6894e89e098a5e
Binary files /dev/null and b/source/_static/guide_merge_request.png differ
diff --git a/source/_static/landing_views.png b/source/_static/landing_views.png
new file mode 100644
index 0000000000000000000000000000000000000000..b72cb0c263d45b416229b24fdf595af8f899c71b
Binary files /dev/null and b/source/_static/landing_views.png differ
diff --git a/source/_static/repo_layout.png b/source/_static/repo_layout.png
new file mode 100644
index 0000000000000000000000000000000000000000..b82c0a64cd99fb9e2aaf2b975f8678d3a18e1696
Binary files /dev/null and b/source/_static/repo_layout.png differ
diff --git a/source/conf.py b/source/conf.py
index 5196e2dd6c5c10a3daabd773a974c52ff7644c87..ccb0909ed5383c6f415dfe55ab44963432034eee 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -109,9 +109,9 @@ extlinks = {
'xios' : ('https://forge.ipsl.jussieu.fr/ioserver/%s', None),
'website' : ('https://www.nemo-ocean.eu/%s' , None),
'zenodo' : ('https://zenodo.org/publication/%s' , None),
- 'gitlab' : (nemo_repo , None),
- 'coderepo': (nemo_repo + '/tree/'+ version + '%s' , None),
- 'tarrepo' : (nemo_repo + '/releases/'+ version + '%s' , None),
+ 'gitlab' : (nemo_repo + '%s' , None),
+ 'coderepo': (nemo_repo + '/tree/'+ version + '%s' , None),
+ 'tarrepo' : (nemo_repo + '/releases/'+ version + '%s' , None),
}
# Include common directives for every rst file
diff --git a/source/editguide.rst b/source/editguide.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9adbcc749b7989643627932b2e9f35c3c476f849
--- /dev/null
+++ b/source/editguide.rst
@@ -0,0 +1,301 @@
+################################
+Making changes to the User Guide
+################################
+
+.. contents::
+ :local:
+
+Overview
+========
+
+The NEMO User guide is a collection of html web-pages that are constructed via the python
+``Sphinx`` package from ReStructured Text (rst) files using the ``Read The Docs`` theme.
+This part of the guide is for developers who wish to edit or add to the guide and for
+maintainers who wish to make those changes live.
+
+These pages will:
+
+* Explain where the source material is located within the GitLab repository
+* Describe how developers can clone the material, edit and build locally.
+* Explain how live html versions can be updated by maintainers (officers)
+
+These pages will not discuss the ReStructured Text syntaxes or directives themselves.
+There are plenty of on-line resources to help with this and the NEMO user-guide rst files
+themselves already contains examples of most of the constructs you are likely to need.
+Simply find a close match to the type of layout you are after, cut-and-paste the section
+and change the content.
+
+.. _LocationGuide:
+
+Location of the source material
+===============================
+
+.. image:: _static/repo_layout.png
+ :align: center
+
+The source material for the user guide appears to be located in multiple locations in the
+NEMO GitLab repository. Two ``User guide`` projects are shown in the systematic above. One
+as a project in the ``Documentation`` subgroup of the ``NEMO Workspaces`` group and one as
+a project in the ``Sites`` group. There is also a ``Draft User guide`` project under
+``Sites``, but more about that later. The apparent duplication is intentional and serves
+to separate the files that any developer can edit from the copies on the publically
+accessible Web server.
+
+The public pages are deployed to a static website by a GitLab Pages server that runs on
+projects in the ``Sites`` group. For security, only Maintainers (i.e. NEMO officers) can
+create and edit projects in the ``Sites`` group. However, the projects under ``Sites``
+only include the source material as a submodule reference to the ``User guide`` project
+under ``NEMO Workspaces``. All developers are able to create issues and merge requests and
+commit to branches of this project. Hence, all developers are able to contribute to the
+user guide. Maintainers can review and accept merge requests like any other development. Any
+merged material will only become live once an officer has updated the submodule reference
+in the appropriate ``Sites`` project.
+
+This may appear confusing but is relatively simple in practise. The next few sections
+illustrate the steps needed to create an issue, merge request and branch, make a change,
+review the change locally, push changes back, have the changes merged and ultimately have
+the html versions created and deployed. The example used for illustration is the creation
+of this very section of the user guide.
+
+.. _IssueGuide:
+
+Preparing to edit the guide
+===========================
+
+Preparation follows the same procedure as any development. I.e. create and issue and
+linked merge request in the GUI for the ``NEMO Workspaces > Documentation > User guide``
+project at `User guide`_
+
+.. _User guide: https://forge.nemo-ocean.eu/nemo/doc/guide
+
+The following images illustrate the process for the changes that created this section of the guide:
+
+* Create a new issue (use the ``users_guide`` label)
+
+.. image:: _static/guide_issue.png
+ :align: center
+ :width: 90%
+
+* Include a brief description
+
+.. image:: _static/guide_issue2.png
+ :align: center
+ :width: 90%
+
+* Create a linked merge request and branch
+
+.. image:: _static/guide_merge_request.png
+ :align: center
+ :width: 90%
+
+.. _CloneGuide:
+
+Cloning and editing the guide
+=============================
+
+With the merge request and new branch in place, the project can be cloned to your local
+machine for editing:
+
+.. code-block:: bash
+
+ git clone --recurse-submodules git@forge.nemo-ocean.eu:nemo/doc/guide.git
+ cd guide
+ git branch -a
+ git switch 10-add-developers-guide-section-on-how-to-make-changes-to-the-user-guide
+
+Note the namelists and gallery subdirectories are submodules. The contents of these are
+unlikely to change often (at least any parts actually used in the user-guide) but, if you
+need to update the references then descend into the appropriate directory and issue the
+update command; e.g.:
+
+.. code-block:: bash
+
+ cd namelists
+ git submodule update --init --force --remote
+ git add namelists
+
+Otherwise, just edit or add to the ``source`` directory content as required. For example:
+
+.. code-block:: bash
+
+ vi source/index.rst
+ vi source/editguide.rst
+ cp ~/Pictures/guide_*.png source/_static/
+ cp ~/Pictures/repo_layout.png source/_static/
+ git add source/_static/guide_*.png source/_static/repo_layout.png
+ git add source/index.rst source/editguide.rst
+
+The ability to preview your changes (and hence check for build-time errors) is an
+essential requirement of the development process. The next section explains how to
+set up and use a suitable environment.
+
+.. _BuildGuide:
+
+Building and previewing
+=======================
+
+To build and preview locally will require:
+
+* A python environment with ``sphinx`` and a few ``sphinx extensions``
+* A browser with access to the local filesystem
+
+Both requirements are easily satisfied on most Unix-based operating systems.
+The `Sphinx installation page`_ lists many ways of installing ``sphinx``.
+Perhaps the easiest being via ``Anaconda`` or ``Miniconda``:
+
+.. _Sphinx installation page: https://www.sphinx-doc.org/en/master/usage/installation.html
+
+.. code-block:: bash
+
+ conda install sphinx
+
+The required extensions are not always available from the default conda server but can be
+easily obtained from alternatives or installed using pip:
+
+.. code-block:: bash
+
+ conda install sphinx_rtd_theme
+ conda install -c conda-forge sphinxcontrib-bibtex
+ python3 -m pip install sphinxext-remoteliteralinclude
+
+As an example, these commands on a Macbook results in the following sphinx install:
+
+.. code-block:: bash
+
+ conda list | grep sphinx
+ sphinx 5.0.2 py37hecd8cb5_0
+ sphinx_rtd_theme 0.4.3 pyhd3eb1b0_0
+ sphinxcontrib-applehelp 1.0.2 pyhd3eb1b0_0
+ sphinxcontrib-bibtex 2.5.0 pyhd8ed1ab_0 conda-forge
+ sphinxcontrib-devhelp 1.0.2 pyhd3eb1b0_0
+ sphinxcontrib-htmlhelp 2.0.0 pyhd3eb1b0_0
+ sphinxcontrib-jsmath 1.0.1 pyhd3eb1b0_0
+ sphinxcontrib-qthelp 1.0.3 pyhd3eb1b0_0
+ sphinxcontrib-serializinghtml 1.1.5 pyhd3eb1b0_0
+ sphinxext-remoteliteralinclude 0.4.0 pypi_0 pypi
+
+With a similar and correctly configured sphinx installation, building the html files
+from the rst files is as simple as:
+
+.. code-block:: bash
+
+ make html
+
+from the top guide directory. A successfu build should look something like:
+
+.. code-block:: bash
+
+ make html
+ sphinx-build -b html -d build/doctrees source build/html
+ Running Sphinx v5.0.2
+ loading pickled environment... checking bibtex cache... up to date
+ done
+ building [mo]: targets for 0 po files that are out of date
+ building [html]: targets for 0 source files that are out of date
+ updating environment: [config changed ('extlinks')] 18 added, 1 changed, 0 removed
+ reading sources... [100%] zooms
+ looking for now-outdated files... none found
+ pickling environment... done
+ checking consistency... done
+ preparing documents... done
+ writing output... [100%] zooms
+ generating indices... genindex done
+ writing additional pages... search done
+ copying images... [100%] _static/agrif_sponge.png
+ copying static files... done
+ copying extra files... done
+ dumping search index in English (code: en)... done
+ dumping object inventory... done
+ build succeeded.
+
+ The HTML pages are in build/html.
+
+ Build finished. The HTML pages are in build/html.
+
+The results can be previewed by opening the ``build/html/index.html`` file in
+your local browser. In my case this is:
+
+.. code-block:: bash
+
+ file:///Users/acc/guide/build/html/index.html
+
+.. note::
+
+ The rendered page may look slightly different to the exact same version eventually
+ built on the NEMO GitLab server. Compare, for example the two images of the landing
+ page below. The html files are identical but the left-hand image is read from the
+ local disk; the right-hand image is as the live user guide is displayed - **in the same
+ browser!** Given this, local previewing should be used to check content and functionality
+ without too much effort on fine tuning of precise layout.
+
+.. image:: _static/landing_views.png
+ :align: center
+
+
+.. _FinalPush:
+
+Send for review and merging
+===========================
+
+After completing your edits and successfully previewing, push back the changes:
+
+.. code-block:: bash
+
+ git add source/_static/guide_*.png source/_static/repo_layout.png
+ git add source/_static/landing_views.png
+ git add source/index.rst source/editguide.rst
+ git commit -m'Added section on how to edit the user-guide. Successfully built and previewed locally'
+ git push origin
+
+In the GUI, go to the merge request page and ``mark as ready``. Contact the reviewer and have the
+changes approved and merged. Your role as developer is now complete.
+
+.. _PublishGuide:
+
+Publishing a new draft user guide
+=================================
+
+Once the new material has been merged, a maintainer can chose to update the live pages
+by updating the submodule link in one of the ``Sites`` projects. In most cases this
+will be the ``Draft User guide`` project since the ``User guide`` project should only
+change when a new code is released. The act of pushing the change back to the GitLab
+server will trigger a pipeline that builds and deploys the html files:
+
+.. code-block:: bash
+
+ git clone git@forge.nemo-ocean.eu:sites/draft-guide
+ cd draft-guide
+ git submodule update --init --force --remote
+ git add guide
+ git commit -m "update of submodule link"
+ git push origin
+
+Once both stages (test and deploy) of the pipeline have successfully completed, the new
+html pages will be available at `https://sites.nemo-ocean.io/draft-guide/`_
+
+.. _https://sites.nemo-ocean.io/draft-guide/: https://sites.nemo-ocean.io/draft-guide/
+
+Publishing a new user guide
+===========================
+
+The same procedure is required when updating the release version of the user guide, with
+the additional recommendation that the commit message mentions which release this commit
+is designed for (and make sure this matches ``versions`` as set in ``source/conf.py``):
+
+Updating of the user guide is expected to occur much less frequently than updating of
+the draft user guide.
+
+.. code-block:: bash
+
+ git clone git@forge.nemo-ocean.eu:sites/user-guide
+ cd user-guide
+ git submodule update --init --force --remote
+ git add guide
+ git commit -m "update of submodule link for release X.X.X"
+ git push origin
+
+Once both stages (test and deploy) of the pipeline have successfully completed, the new
+html pages will be available at `https://sites.nemo-ocean.io/user-guide/`_
+
+.. _https://sites.nemo-ocean.io/user-guide/: https://sites.nemo-ocean.io/user-guide/
+
diff --git a/source/index.rst b/source/index.rst
index 518166e445f9dbcee4b6fa7c278a39af2d51cb56..56f83f930da085cc370ecea47fc2afa6e11bdf72 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -60,10 +60,16 @@ NEMO User Guide
.. toctree::
:hidden:
- :caption: Developer-guide: testing
+ :caption: Developer-guide: Testing
sette
+.. toctree::
+ :hidden:
+ :caption: Developer-guide: Documentation
+
+ editguide
+
.. :Release: |release|
.. figure:: _static/frothyuv.png
diff --git a/source/sette.rst b/source/sette.rst
index 5a1ad001fc9ebeac33a3f014272abe0eeeb0107d..c02a0921b339feb7dcf51cfcc829fd639daf5270 100644
--- a/source/sette.rst
+++ b/source/sette.rst
@@ -3,6 +3,7 @@ A guide to using SETTE
######################
.. contents::
+ :local:
Overview
========