diff --git a/guides/how-to-contribute-to-this-documentation.rst b/contribute.rst
similarity index 76%
rename from guides/how-to-contribute-to-this-documentation.rst
rename to contribute.rst
index 8742d0e6850b4d660e1f4af5ea250addc3c528d4..fafccd2fd2e122ea78340372c59cf83f7dedbe94 100644
--- a/guides/how-to-contribute-to-this-documentation.rst
+++ b/contribute.rst
@@ -1,6 +1,37 @@
-#######################################
-How to contribute to this documentation
-#######################################
+##################
+Contribute to Jami
+##################
+
+Contributions to Jami are always welcome and are much appreciated.
+There are many ways to contribute to Jami, including reporting bugs
+and issues, contributing code, helping package and maintain Jami for
+your GNU/Linux distribution or other operating system, as well as
+contributing to these very docs themselves.
+
+Please see below for how to get started contributing to Jami!
+
+.. contents::
+ :local:
+ :depth: 2
+
+Reporting bugs and issues
+=========================
+
+Please see the :doc:`user/bug-report-guide` for step-by-step
+instructions on how to report bugs and issues you encounter in Jami.
+
+Contributing code
+=================
+
+TODO
+
+Packaging Jami
+==============
+
+TODO
+
+Contributing to this documentation
+==================================
Contributions to these docs are always welcome and appreciated, from
small corrections to whole new chapters.
@@ -13,10 +44,10 @@ every command.
**TODO: internationalization**
Dependencies
-============
+------------
You will need Git installed and configured to use your SSH keypair,
-and an account on the Jami `Gerrit <https://review.jami.net>`_, where
+and an account on the `Jami Gerrit <https://review.jami.net>`_, where
you would send your patches for review. If you need help with this,
see :doc:`the beginning of our patch submission guide
<how-to-submit-a-patch>` (TODO).
@@ -40,7 +71,7 @@ If you want to use the auto-build and auto-refresh feature, also install
$ pip install --upgrade sphinx-autobuild
Cloning the repository
-======================
+----------------------
Clone the repository and configure the push settings like this:
@@ -60,7 +91,7 @@ branch:
$ git checkout -b my-example-change
Editing a page
-==============
+--------------
Pages are written in either markdown or `reStructuredText
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
@@ -70,7 +101,7 @@ raw source of the page and see how it was written.
Go ahead and make your changes to the ``.rst`` or ``.md`` files.
Previewing your work
-====================
+--------------------
From the base of the repository, run:
@@ -92,7 +123,7 @@ Keep this running in the background, then navigate to http://127.0.0.1:8000
(*not* the local .html file).
Saving your work
-================
+----------------
.. code-block:: bash
@@ -113,7 +144,7 @@ For example:
.. code-block:: none
- Add new page section to guides/how-to-contribute-to-this-documentation
+ Add new page section to contribute guide
Add a new section explaining how to add a new page to these docs,
including listing it in the `toctree` directive of the containing
@@ -122,7 +153,7 @@ For example:
GitLab: #123
Submitting a change
-===================
+-------------------
The first time you try to push your changes, Gerrit will complain that
you don't have a Change-Id in your commit, and provide an ``scp``
@@ -136,7 +167,7 @@ should be able to recommit and push your change:
Modifying your work
-===================
+-------------------
A reviewer may ask you to make changes to your patch before merging
it. This is no problem! Simply make the changes, ``git add`` them,
@@ -146,21 +177,21 @@ existing newest commit rather than making a new commit. This is the
workflow for updating a proposed change when using Gerrit.
Adding a page
-=============
+-------------
If you decide to add a whole new page to the documentation, you must
also add it to the ``toctree`` directive of that chapter.
-For instance, if you added a new guide called
-``hosting-jams-on-aws.md`` in the ``guides`` folder, you should add it
-in the ``toctree`` directive of ``guides/index.rst``, *without* the
-file extension:
+For instance, if you added a new page called
+``hosting-jams-on-aws-guide.md`` to the Jami user manual in the
+``user`` folder, you should add it in the ``toctree`` directive of
+``user/index.rst``, *without* the file extension:
.. code-block:: reST
.. toctree::
- bug-report-guide
...
- hosting-jams-on-aws
+ bug-report-guide
+ hosting-jams-on-aws-guide
diff --git a/guides/index.rst b/guides/index.rst
deleted file mode 100644
index bfbbcc7d4d2fa2276dc15a1649dfe3a4b1701c09..0000000000000000000000000000000000000000
--- a/guides/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-######
-Guides
-######
-
-These are how-to guides that should `follow this format
-<https://documentation.divio.com/how-to-guides/>`_.
-
-.. toctree::
- :maxdepth: 1
-
- how-to-contribute-to-this-documentation
- how-to-report-bugs
diff --git a/index.rst b/index.rst
index d9cd4780758887d61e3aac94a33954989ddf2a31..5bda01b6b856a1aa6e5942a0bf78d43f57d9daa5 100644
--- a/index.rst
+++ b/index.rst
@@ -8,8 +8,8 @@ This is the documentation for `Jami <https://jami.net>`_, free/libre
software for universal communication that respects the freedom and
privacy of its users.
-This documentation is community-driven and :doc:`anyone can
-contribute<guides/how-to-contribute-to-this-documentation>`!
+This documentation is community-driven and :ref:`anyone can contribute
+<contribute:Contributing to this documentation>`!
.. note:: You may also be interested in the Jami `daemon
<https://docs.jami.net/doxygen/daemon/>`_ or `libclient
@@ -22,5 +22,4 @@ contribute<guides/how-to-contribute-to-this-documentation>`!
:maxdepth: 2
user/index
- guides/index
technical/index