From b8e124e7372db0ab38cbdbc228ecde5a6c101f99 Mon Sep 17 00:00:00 2001
From: ralf401 <rsc@zammad.com>
Date: Fri, 25 Aug 2023 15:54:21 +0200
Subject: [PATCH] Fixes #372 - Backporting to main

---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 67 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 179fd375..c25d38c3 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,81 @@
-# zammad documentation
+[![Documentation Status](https://readthedocs.org/projects/zammad/badge/?version=pre-release)](https://docs.zammad.org/en/pre-release/?badge=pre-release) (pre-release)
 
-If you want to contribute to the Zammad documentation, just create pull 
-requests.
+[![Documentation Status](https://readthedocs.org/projects/zammad/badge/?version=latest)](https://docs.zammad.org/en/latest/?badge=latest) (latest)
 
-## Documentation
+# Zammad Documentation
 
-Zammad hosts a searchable version of this documentation at 
-https://docs.zammad.org
+Source files for [Zammad’s
+documentation][docs].
+
+## Contributing
+
+If you would like to improve the docs,
+simply:
+
+1. fork the repo,
+2. edit the appropriate `.rst` files
+   (see [Markup Format]
+(#restructuredtext-markup) below),
+and
+3. submit a pull request.
+
+Thanks! ❤ ❤ ❤
+   The Zammad Team
+
+### ReStructuredText Markup
+
+If you like to edit the docs, use the
+ReStructuredText markup language.
+Information about this markup language
+can be found at:
+
+- http://www.sphinx-doc.org/en/stable/
+rest.html
+- https://docutils.sourceforge.io/rst.
+html
+
+### Versioning
+
+This documentation provides versions:
+
+- ``pre-release`` can contain develop,
+not yet released functions and changes
+- ``main`` is the ``latest`` (and
+stable) version of the repository
+- ``stable-x.x`` is the old back port
+for an earlier version
+  - These branches do not receive
+further updates and serve as
+historic help
+    for administrators
 
 ## Notes on Documentation Branches and Pull Requests
 
-Please note that this repository uses protected branches.
-The most current version is **always**  ``main`` - if you create Pull Requests,
-please use ``main`` as destination Branch.
+Please note that this repository uses
+protected branches.
+The most current version is
+**always**  ``pre-release`` - if you
+create
+Pull Requests, please use
+``pre-release`` as destination Branch.
 
-This will ensure that your changes are available upon merge.
+This will ensure that your changes are
+available upon merge.
 
-## ReStructuredText markup
+## Compilation
 
-If you like to edit the docs use the ReStructuredText markup language. 
-Information about this language can be found at:
+### Dependencies
 
-- http://www.sphinx-doc.org/en/stable/rest.html
-- https://docutils.sourceforge.io/rst.html
+* sphinx
 
-Thanks! ❤ ❤ ❤
+  ```
+  $ pip install -r requirements.txt
+  ```
 
-  Zammad Team
+### Example for a local HTML build
 
+```
+make html
+```
 
-[![Documentation Status](https://readthedocs.org/projects/zammad/badge/?version=latest)](https://docs.zammad.org)
+[docs]: https://docs.zammad.org/en/latest/