From d89186a76bd682b4d885e66e85f2e2a944a57958 Mon Sep 17 00:00:00 2001
From: Pierre-Yves Chibon <pingou@pingoured.fr>
Date: Mar 12 2016 08:15:47 +0000
Subject: Adjust documentation based on the feedback from Ralph


---

diff --git a/doc/first_steps.rst b/doc/first_steps.rst
index d1fe76e..cdb42e4 100644
--- a/doc/first_steps.rst
+++ b/doc/first_steps.rst
@@ -9,7 +9,7 @@ Login to pagure or create your account
 
 Pagure has its own user account system.
 
-For instances of pagure such as the one in `pagure.io <https://pagure.io>`_
+For instances of pagure such as the one at `pagure.io <https://pagure.io>`_
 where the authentication is delegated to a third party (in the case of
 pagure.io, the Fedora Account System) via OpenID, the local user account
 is created upon login.
@@ -39,7 +39,7 @@ If you have never generated a ssh key, you can do so by running:
 
     ssh-keygen
 
-or for example on GNOME using the application ``seahorse``.
+or alternatively on GNOME using the application ``seahorse``.
 
 This will create two files in ``~/.ssh/`` (``~`` is the symbol for your home
 folder).
diff --git a/doc/overview.rst b/doc/overview.rst
index bc14f8b..cc4e06b 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -83,6 +83,11 @@ someone is viewing it. For example, while you are reading a ticket if someone
 comments on it, the comment will automatically show up on the page without
 the need for you to reload the entire page.
 
+The flow is: the main pagure server does an action, sends a message over
+redis, the eventsource server picks it up and send it to the browsers waiting
+for it, then javascript code is executed to refresh the page based on the
+information received.
+
 
 Pagure web-hook Server
 -------------------------
@@ -93,3 +98,7 @@ This is the second notifications system in pagure with `fedmsg <http://fedmsg.co
 These notifications are running on their own service to prevent blocking the
 main web application in case the third part service is timing-out or just
 being slow.
+
+The flow is: the main pagure server does an action, sends a message over
+redis, the web-hook server picks it up, build the query and performs the
+POST request to the specified URLs.
diff --git a/doc/pr_custom_page.rst b/doc/pr_custom_page.rst
index d1e57ee..86aa195 100644
--- a/doc/pr_custom_page.rst
+++ b/doc/pr_custom_page.rst
@@ -1,7 +1,7 @@
 Customize the PR page
 =====================
 
-Pagure offers the possibility to customize the page to create pull-request
+Pagure offers the possibility to customize the page that creates pull-request
 to add your specific information, such as: please follow the XYZ coding style,
 run the tests or whatever you wish to inform contributors when they open a
 new pull-request.
diff --git a/doc/ticket_templates.rst b/doc/ticket_templates.rst
index aac6518..9c45651 100644
--- a/doc/ticket_templates.rst
+++ b/doc/ticket_templates.rst
@@ -7,7 +7,7 @@ ignore it, or even to not follow it, but it also helps structuring the
 ticket opened against a project and highlighting the information that are
 often requested/needed.
 
-The templates are providing in the git repository containing the meta-data
+The templates are provided in the git repository containing the meta-data
 for the tickets.
 They must be placed under a ``templates`` folder in this git repository,
 end with ``.md``and as the extension suggests can be formated as markdown.