updated contribute.rst

manuals/other/contribute.rst

@@ -1,64 +1,45 @@
 .. _contribute:
 
-Contribute
-==========
+How to Contribute
+=================
 
-**Everyone's welcome to contribute!**
+This page describes how you can contribute to the manual pages of audiotool yourself.
 
-If you feel like a page could be improved / rewritten, please `create a pull request <https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`__
-with your changes. If you need inspiration, head over to the `issues <https://github.com/audiotool/docs/issues>`_ 
-and pick any issue that is marked with "Help wanted".
+If you're only want to give feedback without making changes yourself, `please create an issue here <https://github.com/audiotool/docs/issues>`_.
 
-We're open even for bigger changes (such as creating new sections, reorganizing sections, etc)! 
-If your idea takes multiple hours to finish however, perhaps it's better to first create an empty draft
-pull request where you outline your idea, so we can comment on it before you start
-working - just to make sure that your time is spent effectively. 
 
-How to contribute
------------------
+Setup
+-----
 
-In general, all manual pages are located in the `manuals <https://github.com/audiotool/manual/tree/main/manuals>`_ directory.
-They're written using the reStructured syntax, see `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ for a quick overview.
+The website you're seeing here is generated based on a set of text files that are written using
+the `reStructured markup syntax <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. 
+These files can be found in `this public repository <https://github.com/audiotool/manual>`_; browse the directory
+called "*manuals*" to get an idea of its structure. If you want to understand more about how the webpage is generated,
+read the documentation of `Sphinx <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_.
 
-If you create new files, you have to reference them from somewhere; either from the index page (in ``index.rst``), or 
-from some page already reference by ``index.rst``. 
 
-See instructions below to see your changes locally. Once you're happy, create
-a pull request, and we'll review your changes & deploy them to production.
+If you have made or want to make changes, please use the forking/pull request workflow described `here <https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`_.
 
 Build locally
--------------
+^^^^^^^^^^^^^
 
-Setup dependencies
-^^^^^^^^^^^^^^^^^^
+The following steps describe how you can build this website locally on your
+computer so see what your changes look like.
 
-* `install sphinx <https://www.sphinx-doc.org/en/master/usage/installation.html>`_
-* install theme: ``python3 -m pip install sphinx_rtd_theme``
+First, you need to:
 
-Build
-^^^^^
+* `install sphinx <https://www.sphinx-doc.org/en/master/usage/installation.html>`_
+* install the theme: ``python3 -m pip install sphinx_rtd_theme``
 
-In the project directory, simply type::
+Then, everytime you make a change [#rebuild]_, rebuild with:: 
 
     make html
 
+You can view your changes by opening the file file ``_build/html/index.html`` in your webbrowser.
 
-Note  that this will only rebuild pages for which the source changed.
-This means e.g. the sidebar won't update for old documents if you ad a new document.
-
-To rebuild all pages, first fo ``make clean`` before doing ``make html``.
-
-View
-^^^^
-
-Open the file ``_build/html/index.html`` in your favourite webbrowser.
 
-
-Troubleshoot
-------------
-
-Can't install ``python3-sphinx`` / ``make html`` command throws error
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Troubleshooting ``make html`` not working
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If for whatever reason the above setup doesn't work, you can also install the sphinx 
 package directly in python::
@@ -72,4 +53,11 @@ And then call the ``make html`` command manually from the project cirectory::
     python3 -m sphinx html _build/html .
 
 
-Make sure you have install the theme as described above.
+Make sure you have install the theme as described above.
+
+
+.. [#rebuild] Note  that this will only rebuild pages for which the source changed.
+    This means e.g. the sidebar won't update for old documents if you ad a new document.
+
+    To rebuild all pages, first fo ``make clean`` before doing ``make html``. If you're using sphinx
+    directly, simply delete all contents of ``_build/html``.