apply suggestions and split some pages

docs/source/maintaining_a_kit/improving.rst

@@ -24,72 +24,26 @@ This may include (but is not limited to):
 - **More tests**: can you get to 100% coverage?!
 - **More documentation**: Explain each part of your code. Add examples. Make
   your documentation visually appealing and easy to navigate!
-- :ref:`Add a logo <logo>`: Spice up your MDAKit with your very own logo!
-- **Use tooling and workflows**: don't rely solely on the MDAKit Registry's CI 
-  run - set up your own automated testing and alerts!
+- **Use tooling and workflows**: set up and personalise automatic features to
+  check code formatting, run your own automated testing (don't rely solely on 
+  the MDAKit Registry's CI!), automatically publish new releases, and more!
 - **Community resources**: make it easy for users to report issues, ask 
   questions - or even contribute to your MDAKit themselves!
 - **Release on PyPi/conda-forge**: make it easier for users to install your kit! 
 - :ref:`Make a journal publication <publishing>`: get recognition for your code!
 
-If applicable, remember to :ref:`update your kit's metadata <update-metadata>` 
-so new features are reflected on the Registry.
+You could even opt to :ref:`add a logo <logo>` to add unique flair to your MDAKit!
 
 
-.. _update-metadata:
-
-Updating the MDAKit's metadata
-==============================
-As your kit evolves, you may wish to update the information displayed on the
-MDAKit's registry - for example, to expand the description, add a publication, 
-or update the installation instructions.
-
-If this is the case, simply edit your kit's ``metadata.yaml`` in your fork of 
-the ``MDAKits`` repository, then make a new Pull Request (PR). The MDAKits team will then 
-review and merge your PR to apply the changes.
-
-
-.. _publishing:
-
-Publishing your MDAKit!
-=======================
-Publishing an article in a journal such as `JOSS <https://joss.readthedocs.io/>`_
-is a good way to get recogneition for your work and provide a citable source for
-users.
-
-`JOSS papers`_ are short, relatively simple, and in meeting the requirements
-for registering an MDAKit, you will have already met many of the JOSS submission 
-requirements. Once you've built up your kit's documentation and testing, 
-consider publication with JOSS or a similar journal!
-
-
-.. _logo:
-
-Adding a logo for your MDAKit
-=============================
-A custom logo can add some pizazz to your MDAKit. You are welcome to create an
-entirely custom logo, use the default `'empty gear' template`_, 
-or modify the template - feel free to place your logo within the gears!
-
-If you used the MDAKits cookiecutter, there is already a placeholder logo in 
-your documentation. The `MDAKits cookiecutter documentation`_ has information 
-on updating this.
-
 .. note::
-   MDAnalysis recommends that kit authors carefully check that any material used 
-   in their kit - including logos - is used under appropriate licenses, and do
-   not infringe on any copyrights. 
-
-   MDAnalysis cannot give any legal advice on these matters; if you are unsure 
-   about any legal matters, please consult a lawyer.
-
 
-.. _`MDAKits cookiecutter documentation`:
-   https://cookiecutter-mdakit.readthedocs.io/en/latest/usage.html#documentation-configuration
+    If applicable, remember to :ref:`update your kit's metadata <update-metadata>` 
+    so changes and additions are reflected on the Registry.
 
-.. _`JOSS papers`:
-   https://joss.readthedocs.io/en/latest/submitting.html#submission-process
 
-.. _`'empty gear' template`:
-   https://github.com/MDAnalysis/branding/tree/main/templates/MDAKits
+.. toctree::
+   :maxdepth: 1
+   :caption: Index
 
+   publishing
+   logo

docs/source/maintaining_a_kit/keep-healthy.rst

@@ -2,30 +2,50 @@
 Keeping an MDAKit healthy
 *************************
 
-.. _failingci:
 
-If an MDAKit fails the weekly CI
-================================
+The MDAKit Registry CI
+######################
+
+
+.. _mdakitsci:
+
+What is the 'MDAKit Registry CI'?
+---------------------------------
+
+The MDAKit Registry Continuous Integration is run twice a week and involves the 
+(automatic) running of each kit's tests (as specified in the ``metadata.yaml`` 
+file.
+
+If the tests **pass**, the kit's 'CI badges', which appear on the 
+:ref:`Registry <mdakits>` and are visibile to all potential users, remain green.
 
-In the event that a kit no longer passes its tests, an issue is automatically
-raised on the `MDAKits Registry GitHub issue tracker`_, the maintainers (as identified in 
-``metadata.yaml``) are notified, and the kit's CI badges appearing on the 
-:ref:`Registry <mdakits>` will be updated.
+If the tests **fail**, an issue is automatically raised on the 
+`MDAKits Registry GitHub issue tracker <https://github.com/MDAnalysis/MDAKits/issues>`_, 
+the maintainers (as identified in 
+``metadata.yaml``) are notified, and the CI badges updated to red to inform
+others.
 
-Note that two tests are run:
+Note that there are two CI runs:
 
-- **develop**, using the 'current' version of your MDAKit (installed when
-  running the commands under ``src_install`` in ``metadata.yaml``), and the
-  current ``develop`` branch of MDAnalysis.
+- **develop**, using the 'source' version (assumed to be the development 
+  version) of your MDAKit (i.e., what is installed when running the commands 
+  under ``src_install`` in ``metadata.yaml``), and the current ``develop`` 
+  (under active development) branch of MDAnalysis.
 
 - **latest**, (if applicable) using the latest release of your MDAKit (installed
   when running the commands under ``install`` in ``metadata.yaml``), and the 
   most recent release of MDAnalysis.
 
-Depending on the nature of the failure, one or both of **develop** and 
-**latest** may be failing.
+Depending on the nature of the failure, one or both of *develop* and 
+*latest* may be failing. In many cases it will be only *develop* failing, as the 
+effects of new changes to your kit (or to MDAnalysis) will be seen here as they
+are made, but only in *latest* after the changes are published in a new release. 
+Having *develop* gives you a chance to find and fix errors before they are 
+carried through to a release, avoiding impacting (most) users.
 
 
+.. _failingci:
+
 Why did CI fail?
 ----------------
 There are a number of reasons that the CI tests may fail - it could be an
@@ -34,12 +54,14 @@ are needed to keep in line with changes within MDAnalysis or other dependencies.
 It may reflect a single test that is no longer passing, or that a larger error
 is preventing your kit from being installed/any tests from being run.
 
-If you don't already have an idea what is causing your kit to fail, you can read
-the CI log file to find the exact point of failure and accompanying error 
-messages:
+You may already know the likely source of your kit's failure. If you have your own
+CI, this could be a place to start.
+
+Otherwise, you can read the CI log file for the MDAKit Registry CI run to find the 
+exact point of failure and accompanying error messages:
 
-#. Click on the *'Actions'* tab on the 
-   `MDAKits Github page <https://github.com/MDAnalysis/MDAKits/>`_.
+#. Click on the `Actions tab <https://github.com/MDAnalysis/MDAKits/actions>`_ on 
+   the MDAKits Github page.
 
 #. Click on the most recent *'GH Actions Cron CI'* job.
 
@@ -57,16 +79,25 @@ Fixing an failure
 -----------------
 Once the point of failure has been identified, you can set about trying to fix
 it. The exact fix required will of course depend on exactly what went wrong, but
-hopefully the error message(s) in the log will be enough to get you started.
+hopefully the error message(s) in the log will be enough to get you started. If
+you believe the issue is due to a breaking behaviour change in MDAnalysis, we
+encourage you to raise an issue on the 
+`core library issue tracker <https://github.com/MDAnalysis/mdanalysis/issues>`_.
 
 Any fixes will be applied in your kit's home repository - no direct interaction
-with the Registry is required. 
+with the Registry is required.
 
 If you're still not sure what's gone wrong or how to fix it, you can comment on 
 the issue that was raised on the `MDAKits GitHub`_. The MDAKits team, or
 other members of the community, may be able to help - but remember, ultimate
 responsibility remains with **you**. 
 
+.. note::
+
+   If your fix affects any your kit's metadata.yaml, e.g. if the installation
+   instructions changed, rember to 
+   :ref:`update your metadata <update-metadata>` as appropriate.
+
 
 After applying a fix
 --------------------
@@ -85,18 +116,26 @@ Avoid failing tests before they happen!
 
 Just as you are likely to keep improving your kit, the upstream packages on
 which it relies - including MDAnalysis - will also continue to evolve. 
-Sometimes, this means that things your kit relies on will no longer work. 
+Sometimes, this means that the parts of your kit that rely on these packages 
+will no longer work. 
 Keeping an eye out for such changes will allow you to modify your kit 
 appropriately *before* the upstream change is fully applied and your code 
 starts to fail.
 
 Usually, a package will warn users of any upcoming changes that may affect
 downstream usage (e.g. changing how a function is to be used), by raising
-a warning indicating the upcoming change when the function is used. 
-If your kit relies on any such to-be-changed features, then (assuming the 
-relevant code is covered by your kit's tests) these warnings will be triggered 
-when running the tests and will appear in the logs of the automated CI runs - 
-it pays to keep an eye on these!
+a `DeprecationWarning <https://docs.python.org/3/library/exceptions.html#DeprecationWarning>`_
+indicating the upcoming change when used. 
+If your kit relies on any such to-be-changed features, these warnings will
+be triggered when accessing the deprecated feature, and (assuming the relevant
+core is covered by your kit's tests) will appear in the output logs, so it's a
+good idea to keep an eye on these.
+
+Testing against *development* versions of packages, not just the latest release,
+can also allow you to catch issues early. The :ref:`MDAKits Registry CI <mdakitsci>` 
+tests both the latest release and development versions of your kit and MDAnalysis. 
+If you've used the MDAKits cookiecutter, the generated GitHub workflow tests with
+both the development and latest release of MDAnalysis.
 
 It is also a good idea check release notes for new releases of packages your kit
 uses and watch for any announcements of major upcoming changes.

docs/source/maintaining_a_kit/logo.rst

@@ -0,0 +1,28 @@
+.. _logo:
+
+Adding a logo for your MDAKit
+=============================
+A custom logo can add some pizazz to your MDAKit. You are welcome to create an
+entirely custom logo, use the default `'empty gear' template`_, 
+or modify the template - feel free to place your logo within the gears!
+
+If you used the MDAKits cookiecutter, there is already a placeholder logo in 
+your documentation. The `MDAKits cookiecutter documentation`_ has information 
+on updating this.
+
+.. note::
+   MDAnalysis recommends that kit authors carefully check that any material used 
+   in their kit - including logos - is used under appropriate licenses, and do
+   not infringe on any copyrights. 
+
+   MDAnalysis cannot give any legal advice on these matters; if you are unsure 
+   about any legal matters, please consult a lawyer.
+
+
+.. _`MDAKits cookiecutter documentation`:
+   https://cookiecutter-mdakit.readthedocs.io/en/latest/usage.html#documentation-configuration
+
+
+.. _`'empty gear' template`:
+   https://github.com/MDAnalysis/branding/tree/main/templates/MDAKits
+

docs/source/maintaining_a_kit/publishing.rst

@@ -0,0 +1,21 @@
+.. _publishing:
+
+Publishing your MDAKit!
+=======================
+Providing a way to easily cite your MDAKit - e.g by having an associated DOI -
+can make it easier for users to share your code and for you to get recognition
+when someone uses your work.
+
+Ideally, you could publish an article about your kit in a journal such as 
+`JOSS <https://joss.readthedocs.io/>`_. JOSS papers are short and
+`relatively simple <https://joss.readthedocs.io/en/latest/submitting.html#submission-process`>_ -
+In meeting the requirements for registering an MDAKit, you will have already
+met many of the JOSS submission requirements. Once you've built up your kit's
+documentation and testing, consider publication with JOSS or a similar journal!
+
+If you don't have a publication to directly associated with your MDAKit, we 
+recommend at least generating a DOI for your code repository, e.g through 
+`Zenodo <https://zenodo.org/>`_. If you log in to Zenodo using your GitHub 
+account, you can easily do this from the 
+`Zenodo GitHub page <https://zenodo.org/account/settings/github/>`_.
+

docs/source/maintaining_a_kit/updatemetadata.rst

@@ -0,0 +1,18 @@
+.. _update-metadata:
+
+Updating the MDAKit's metadata
+==============================
+As your kit evolves, you may find the information you supplied in the 
+:ref:`metadata <specification>` file at registration is no longer valid (e.g.
+the installation instructions mught require updating), or wish to otherwise
+alter or add new details (e.g. adding a publication, or expanding the 
+description).
+
+**If you don't update your metadata, potential users could be getting the wrong
+information, and/or the automated tests run by the MDAKit Registry could fail.**
+
+To update your kit's metadata, simply edit the kit's ``metadata.yaml`` (in your
+fork of the ``MDAKits`` repository), then make a new Pull Request (PR). The 
+MDAKits team will then review and merge your PR to apply the changes.
+
+

docs/source/maintainingakit.rst

@@ -9,35 +9,39 @@ Maintaining an MDAKit
    like to see covered here, please get in touch via 
    `MDAnalysis Github Discussions`_.
 
-Successfully registering an MDAKit is not the end of the journey! Like a pet, a
+Successfully registering an MDAKit is not the end of the journey! A
 software package still requires input to keep it healthy and thriving. 
 This includes both expanding and adding new features and ensuring the MDAKit 
 continues to run as intended. **While not required for an MDAKit to remain in
-the registry, such activities are highly encouraged**.
+the registry, such activities are highly encouraged**. 
 
-There are a variety of reasons a kit may behave unexpectedly after being 
-submitted to the registry. Apart from actively developing the kit, changes in 
-kit dependencies, or even Python itself, can introduce/deprecate new/old 
-functionality. 
 
-As part of the MDAKit Registry, your kits' tests (as specified in 
-``metadata.yaml``) are automatically rerun twice each week, so that you (and potential 
-users) have assurance that your code still works as intended, or are notified
-when it does not. 
+Now that it is registered, your kit will be part of the :ref:`MDAKits Registry CI <mdakitsci>`:
+your kits' tests (as specified in ``metadata.yaml``) are automatically rerun 
+twice each week, so that you (and potential users) have assurance that your 
+code still works as intended, or are notified when it does not. 
 
 **However, the ultimate responsibility for maintaining your MDAKit remains with
 you.**
 
+
 The sections below provide some information to keep in mind for maintaining your
 MDAKit after registration.
 
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    maintaining_a_kit/keep-healthy
+   maintaining_a_kit/updatemetadata
+
+.. toctree::
+   :maxdepth: 2
+
    maintaining_a_kit/improving
 
 
+
 .. _`MDAnalysis GitHub Discussions`:
    https://github.com/MDAnalysis/mdanalysis/discussions