Improve documentation

diff --git a/app/flatpages/help/release_webhooks.md b/app/flatpages/help/release_webhooks.md
index 90c6c25a47c0cb43f0197b6a99f0428a055ad347..e9a9f8185bbfe9ddbf8f1cc6f2e2ad1ff791c82d 100644 (file)
--- a/app/flatpages/help/release_webhooks.md
+++ b/app/flatpages/help/release_webhooks.md
@@ -2,6 +2,9 @@ title: Creating Releases using Webhooks
 
 ## What does this mean?
 
+A webhook is a notification from one service to another. Put simply, a webhook
+is used to notify ContentDB that the git repository has changed.
+
 ContentDB offers the ability to automatically create releases using webhooks
 from either Github or Gitlab. If you're not using either of those services,
 you can also use the [API](../api) to create releases.
@@ -12,7 +15,7 @@ The process is as follows:
    for Github.
 2. The user pushes a commit to the git host (Gitlab or Github).
 3. The git host posts a webhook notification to ContentDB, using the API token assigned to it.
-4. ContentDB checks the API token and issues a new releases.
+4. ContentDB checks the API token and issues a new release.
 
 <p class="alert alert-info">
        This feature is in beta, and is only available for Trusted Members.
@@ -25,9 +28,14 @@ The process is as follows:
 1. Go to your package page.
 2. Make sure that the repository URL is set to a Github repository.
    Only github.com is supported.
-3. Click "Set up a webhook to create releases automatically" below the releases
-   panel on the side bar.
-4. Grant ContentDB the ability to manage Webhooks
+3. Go to "Create a release", and click "Setup webhook" at the top of the page.
+   If you do not see this, either the repository isn't using Github or you do
+   not have permission to use webhook releases (ie: you're not a Trusted Member).
+4. Grant ContentDB the ability to manage Webhooks.
+5. Set the event to either "New tag" or "Push". New tag is highlight recommended.
+
+   N.B.: GitHub uses tags to power GitHub Releases, meaning that creating a webhook
+   on "new tag" will sync GitHub and ContentDB releases.
 
 ### GitHub (manual)