Suggested updates to "Contributing To The Documentation"

[stevepiercy]

Now that we can build the docs locally via tox, I think we should update the docs for contributing for the power user audience. In "Contributing To The Documentation" (about/contributing/index), under "Editing The Docs Using Git":

* Learn about `Sphinx <http://sphinx-doc.org/>`_ and `restructured text
  <http://sphinx-doc.org/rest.html>`_.

* Edit the file(s) which you want to update.

* Check that you do not have any syntax errors or typos

* Commit your changes and `create <https://help.github.com/articles/creating-a-pull-request>`_ and open `pull <https://help.github.com/articles/using-pull-requests>`_ request.

For more information about writing documentation please read the :doc:`styleguide <documentation_styleguide>` and the docs about :doc:`Helper tools <helper_tools>`.

1. The following bullet point is not necessary for this audience (advanced users):

   • Edit the file(s) which you want to update.

2. The following bullet point should refer to whatever automated spelling and syntax checking tools are used, e.g., spinxcontrib.spelling and tox for build warning and error messages. What tools do we recommend that developers use? Suggest "Run tox to build the docs locally and use the automatic syntax and spelling tools."

   • Check that you do not have any syntax errors or typos

3. Suggest the last paragraph be rewritten as follows:

   * Follow the :doc:`Plone Documentation Styleguide <documentation_styleguide>`.
   
   We have collected a list of some :doc:`Helper Tools For Writing Documentation <helper_tools>`.

[svx]

I am sorry, but the audience is more than 'only' developer.

Further we will remove tox, see #929.

For the "GitHub Ribbon" we have that already covered in the new theme.

[stevepiercy]

Setting aside tox, I think the suggested edits have some merit. Please don't throw the baby out with the bathwater.

[polyester]

It is a good idea to review the part on "contributing to the docs" and even more carefully split it out in audiences than it is now:

• "willing to do a quick fix", don't want to download the internet and set up programs to do that
• "I actually live in vim/emacs for most of my life"

(eh, these are not the labels I would propose, to be clear ;-)

I'll have a good look over it in the next few days and try to come up with suggestions

[stevepiercy]

They're pretty clear to me 😉

Thanks for diving in.

[stevepiercy]

Fixed. https://6.docs.plone.org/contributing/documentation/