Improve wording in dev-docs. Re #24293

dev-docs/source/Standards/AdditionalPythonCode.rst

@@ -15,37 +15,40 @@ related to the Python exports (``mantid.*`` modules) nor an integral part of
 ``workbench`` should go to either the ``scripts`` directory or ``qt``
 directory.
 
-``scripts`` is a place to put non-GUI modules and scripts such as pure Python
+``scripts`` is a place to put non-GUI modules and scripts such as pure Python 
 reduction frameworks or technique specific plotting modules which are 
-desirable to be included in an official release. The code in ``scripts`` can
-be included in the automatic unit testing machinery making it possible to
-avoid breakages due to changes in Mantid's core parts. Although some reduction
-interface code lives ``scripts``, adding more GUI related code there is 
+desirable to be included in an official release. The code in ``scripts`` can 
+be included in the automatic unit testing machinery making it possible to 
+avoid breakages due to changes in Mantid's core parts. Although some reduction 
+interface code lives in ``scripts``, adding more GUI related code there is 
 discouraged. 
 
-New Python interfaces should go to the ``qt`` directory.
+Python interfaces should go to the ``qt`` directory.
 
 The ``scripts`` directory
 #########################
 
-New Python code
----------------
-
-New code should go in ``scripts/modulename`` directory. They can then be
-imported into Mantid simply by ``import modulename``.
+Python code should be written as proper `modules 
+<https://docs.python.org/3/tutorial/modules.html>`_. For example, the code of 
+a module called ``spam`` should go into ``scripts/spam`` and contain a file 
+named ``__init__.py`` at minimum. Then the module can be imported into Mantid 
+simply by ``import spam``.
 
 Documentation
 -------------
 
-Currently, there is no official place to put documentation for the code in
-``scripts``. However, *Concepts* and *Techniques* categories should cover most
-use cases of ``scripts``.
+Documentation can be added to Mantid's Python API docs in ``docs/source/api`` 
+and linked to ``docs/source/api/index.rst``. Note, that it is possible to 
+import Python's docstrings in ``.rst`` files using directives such as ``.. 
+automodule::`` or ``.. autoclass::``, see `here 
+<http://www.sphinx-doc.org/es/stable/ext/autodoc.html>`_.
 
 Unit testing
 ------------
 
-Unit tests should be added to ``scripts/test/modulename``. The tests follow the
-:ref:`standard Mantid unit testing practices <UnitTestGoodPractice>`.
+Unit tests for each module should be added to ``scripts/test/modulename``. The 
+tests follow the :ref:`standard Mantid unit testing practices 
+<UnitTestGoodPractice>`.
 
 The ``qt`` directory
 ####################