update documentation for GitHub change hook

* misc syntax, wording and cosmetic changes
* move mention of standalone server to the beginning of the section
* fix link to the GitHub tutorial for adding webhooks
* make list of parameters of GitHub webhook and their correpsonding
  values explicit

See ticket:2938

master/docs/manual/cfg-wwwhooks.rst

@@ -26,19 +26,36 @@ The ``base`` dialect must be enabled for this to work.
 GitHub hook
 +++++++++++
 
+.. note::
+
+   There is a standalone HTTP server available for receiving GitHub notifications as well: :file:`contrib/github_buildbot.py`.
+   This script may be useful in cases where you cannot expose the WebStatus for public consumption.
+
 The GitHub hook is simple and takes no options.
 
-::
+.. code-block:: python
 
     c['www'] = dict(...,
-        change_hook_dialects={ 'github' : True }))
+        change_hook_dialects={'github': True}))
 
-With this set up, add a Post-Receive URL for the project in the GitHub administrative interface, pointing to ``/change_hook/github`` relative to the root of the web server.
-For example, if the grid URL is ``http://builds.example.com/bbot/grid``, then point GitHub to ``http://builds.example.com/bbot/change_hook/github``.
-To specify a project associated to the repository, append ``?project=name`` to the URL.
+Having added this line, you should add a webhook for your GitHub project (see `Creating Webhooks page at GitHub <https://developer.github.com/webhooks/creating/>`_).
+The parameters are:
+
+:guilabel:`Payload URL`
+    This URL should point to ``/change_hook/github`` relative to the root of the web status.
+    For example, if the grid URL is ``http://builds.example.com/bbot/grid``, then point GitHub to ``http://builds.example.com/bbot/change_hook/github``.
+    To specify a project associated to the repository, append ``?project=name`` to the URL.
+
+:guilabel:`Content Type`
+    Specify ``application/x-www-form-urlencoded``.  JSON is not currently not supported.
+
+:guilabel:`Secret`
+    Any value.  Currently this parameter is not supported.
+
+:guilabel:`Which events would you like to trigger this webhook?`
+    Leave the default -- ``Just the push event`` -- other kind of events are not currently supported.
 
-Note that there is a standalone HTTP server available for receiving GitHub notifications, as well: :file:`contrib/github_buildbot.py`.
-This script may be useful in cases where you cannot expose the web server for public consumption.
+And then press the ``Add Webhook`` button.
 
 .. warning::
 
@@ -56,9 +73,9 @@ And create a file ``changehook.passwd``
 
     user:password
 
-Then, create a GitHub service hook (see https://help.github.com/articles/post-receive-hooks) with a WebHook URL like ``http://user:password@builds.example.com/bbot/change_hook/github``.
+Then change the the ``Payload URL`` of your GitHub webhook to ``http://user:password@builds.example.com/bbot/change_hook/github``.
 
-See the `documentation <https://twistedmatrix.com/documents/current/core/howto/cred.html>`_ for twisted cred for more option to pass to ``change_hook_auth``.
+See the `documentation for twisted cred <https://twistedmatrix.com/documents/current/core/howto/cred.html>`_ for more options to pass to ``change_hook_auth``.
 
 Note that not using ``change_hook_auth`` can expose you to security risks.