Update Documentation

doc/changes/unreleased.md

@@ -15,6 +15,7 @@
 * Updated design doc (Added known Issues)
 * Updated migration progress table
 * Updated the FAQ with an entry about the ``isort`` compatibility issue
+* [#351](https://github.com/exasol/python-toolbox/issues/351), [#352](https://github.com/exasol/python-toolbox/issues/352): updated user guide
 
 ## 🔧 Changed
 * Updated `actions/upload-artifacts` version to `4.6.0`

doc/user_guide/features.rst

@@ -0,0 +1,34 @@
+Features
+========
+
+Uniform Project Layout
+----------------------
+
+PTB expects a default project layout following "convention over configuration" when possible and reasonable.
+See the cookie-cutter project template for details, which is part of the python-toolbox workspace and can be found in directory `project-template`.
+You can also generate a project from the template to explore the default structure.
+For more details on this, please check out section `"getting started" <getting_started.html>`_ section.
+
+Nox
+---
+
+The most central tool when interacting with the toolbox is :code:`nox`, which is the task runner used across all of Exasol's Python-based projects.
+The toolbox itself provides various standard tasks and a plugin mechanism to extend these tasks if needed. For more information regarding nox, please visit the `nox homepage <http://nox.thea.codes/en/stable/>`_.
+
+Central files in regards to nox and the toolbox are:
+
+- noxfile.py: Standard nox configuration/setup file
+- noxconfig.py: Exasol-specific file containing additional information needed by the standard tasks of the toolbox
+
+Important Nox Commands
+^^^^^^^^^^^^^^^^^^^^^^
+
+* :code:`nox -l` shows a list of all available nox tasks
+* :code:`nox -s <tasks>` run the specified task(s)
+    * :code:`nox -s test:typing` runs the type checker on the project
+    * :code:`nox -s docs:clean docs:build docs:open`
+        #. first task removes the documentation folder
+        #. second one builds the documentation
+        #. last one opens the documentation in the web browser
+* :code:`nox` without :code:`-s` runs the default task which is
+    * :code:`nox -s project:fix` this command runs automated fixes on the code

doc/user_guide/how_to_release.rst

@@ -0,0 +1,12 @@
+How to Release?
+===============
+
+#.  Use :code:`nox -s release:prepare` to prepare the project for a new release.
+#.  Merge your **Pull Request** to the **default branch**
+#.  Use :code:`git remote show origin | sed -n '/HEAD branch/s/.*: //p'` to output the **default branch**
+#.  Use :code:`git checkout <default branch>` Switch to the **default branch**
+#.  Use :code:`git pull` to update branch
+#.  Use :code:`TAG=<name>` to set a variable named **"TAG"**
+#.  Use :code:`git tag "${TAG}"` to create a new tag in your repo
+#.  Use :code:`git push origin "${TAG}"` to push it to remote
+#.  GitHub workflow **CD** reacts on this tag and starts the release process

doc/user_guide/user_guide.rst

@@ -6,8 +6,9 @@
 .. toctree::
     :maxdepth: 2
 
-    overview
     getting_started
+    features
     workflows
     customization
     migrating
+    how_to_release