CONTRIBUTING: Doc section

CONTRIBUTING.rst

@@ -8,27 +8,27 @@ Reporting Issues/Bugs
 Thanks for `reporting issues to ARTIQ
 <https://github.com/m-labs/artiq/issues/new>`_! You can also discuss issues and
 ask questions on IRC (the #m-labs channel on OFTC), the `Mattermost chat
-<https://chat.m-labs.hk>`_, or on the `forum <https://forum.m-labs.hk>`_.
+<https://chat.m-labs.hk>`_, or in the `forum <https://forum.m-labs.hk>`_.
 
 The best bug reports are those which contain sufficient information. With
 accurate and comprehensive context, an issue can be resolved quickly and
 efficiently. Please consider adding the following data to your issue
 report if possible:
 
-* A clear and unique summary that fits into one line. Also check that
+* A clear and unique summary that fits into one line. Check that this
-  this issue has not yet been reported. If it has, add additional information there.
+  issue has not yet been reported; if it has, add additional information there.
-* Precise steps to reproduce (list of actions that leads to the issue)
+* Precise steps to reproduce (a list of actions that leads to the issue)
 * Expected behavior (what should happen)
 * Actual behavior (what happens instead)
-* Logging message, trace backs, screen shots where relevant
+* Logging message, tracebacks, screenshots, where applicable
 * Components involved (omit irrelevant parts):
 
-  * Operating System
+  * Operating system used
-  * ARTIQ version (with recent versions of ARTIQ, run ``artiq_client --version``)
+  * ARTIQ version (run any command in the form of ``artiq_client --version``)
-  * Version of the gateware and runtime loaded in the core device (in the output of ``artiq_coremgmt -D .... log``)
+  * Gateware and firmware loaded to the core device (in the output of
+    ``artiq_coremgmt [-D ....] log``)
   * Hardware involved
 
-
 For in-depth information on bug reporting, see:
 
 http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
@@ -38,8 +38,8 @@ https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines
 Contributing Code
 =================
 
-ARTIQ welcomes contributions. Write bite-sized patches that can stand alone,
+ARTIQ welcomes contributions. Write bite-size patches that can stand alone,
-clean them up, write proper commit messages, add docstrings and unittests. Then
+clean them up, write proper commit messages, add docstrings and unit tests;
 ``git rebase`` them onto the current master or merge the current master. Verify
 that the test suite passes. Then submit a pull request. Expect your contribution
 to be held up to coding standards (e.g. use ``flake8`` to check yourself).
@@ -51,7 +51,7 @@ Checklist for Code Contributions
 - Use correct spelling and grammar. Use your code editor to help you with
   syntax, spelling, and style
 - Style: PEP-8 (``flake8``)
-- Add, check docstrings and comments
+- Add or update docstrings and comments
 - Split your contribution into logically separate changes (``git rebase
   --interactive``). Merge (squash, fixup) commits that just fix previous commits
   or amend them. Remove unintended changes. Clean up your commits.
@@ -63,12 +63,37 @@ Checklist for Code Contributions
 - Review each of your commits for the above items (``git show``)
 - Update ``RELEASE_NOTES.md`` if there are noteworthy changes, especially if
   there are changes to existing APIs
-- Check, test, and update the documentation in `doc/`
+- Check, test, and update the documentation in ``doc/``
 - Check, test, and update the unit tests
 - Close and/or update issues
 
+
+Contributing Documentation
+==========================
+
+ARTIQ welcomes documentation contributions. The ARTIQ manual is hosted online in HTML
+form `here <https://m-labs.hk/artiq/manual/>`__ and in PDF form
+`here <https://m-labs.hk/artiq/manual.pdf>`__. It is generated from source files
+in ``doc/manual``, written in a variant of the
+`reStructured Text <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+markup language processed by `Sphinx <https://www.sphinx-doc.org/en/master/>`_, with
+some of the additional reference material processed from inline documentation
+in the ARTIQ source itself.
+
+Write bite-size patches that can stand alone, clean them up, write proper commit 
+messages. Check that your edits render properly and compile without errors: ::
+
+  $ nix build .#artiq-manual-pdf
+  $ nix build .#artiq-manual-html
+
+Elaborations, improvements, clarifications and corrections to any of the material
+are happily accepted, but special attention is drawn to the manual
+`FAQ <https://m-labs.hk/artiq/manual/faq.html>`_, where tips and solutions
+are especially easy to add. See also the FAQ's own
+`section on the subject <https://m-labs.hk/artiq/manual/faq.html#build-documentation>`_.
+
 Copyright and Sign-Off
-----------------------
+======================
 
 Authors retain copyright of their contributions to ARTIQ, but whenever possible
 should use the GNU LGPL version 3 license for them to be merged.
@@ -108,7 +133,7 @@ can certify the below:
             maintained indefinitely and may be redistributed consistent with
             this project or the open source license(s) involved.
 
-then you just add a line saying
+then add a line saying
 
         Signed-off-by: Random J Developer <random@developer.example.org>