diff --git a/doc/repmgrd-bdr.sgml b/doc/repmgrd-bdr.sgml
index 13520d81..aa3f97a8 100644
--- a/doc/repmgrd-bdr.sgml
+++ b/doc/repmgrd-bdr.sgml
@@ -174,17 +174,13 @@
     <para>
       Key to "failover" execution is the <literal>event_notification_command</literal>,
       which is a user-definable script specified in <filename>repmpgr.conf</filename>
-      and which should reconfigure the proxy server/ connection pooler to point
-      to the other, still-active node.
+      and which can use a &repmgr; <link linkend="event-notifications">event notification</link>
+      to reconfigure the proxy server / connection pooler so it points to the other, still-active node.
+      Details of the event will be passed as parameters to the script.
     </para>
     <para>
-      Each time &repmgr; (or <application>repmgrd</application>) records an event,
-      it can optionally execute the script defined in
-      <literal>event_notification_command</literal> to take further action;
-      details of the event will be passed as parameters.
-    </para>
-    <para>
-      Following placeholders are available to the script:
+      Following parameter placeholders are available for the script definition in <filename>repmpgr.conf</filename>;
+      these will be replaced with the appropriate value when the script is executed:
     </para>
 
     <variablelist>
@@ -231,20 +227,35 @@
           </para>
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term><option>%c</option></term>
+        <listitem>
+          <para>
+            conninfo string of the next available node (<varname>bdr_failover</varname>)
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>%a</option></term>
+        <listitem>
+          <para>
+            name of the next available node (<varname>bdr_failover</varname>)
+          </para>
+        </listitem>
+      </varlistentry>
     </variablelist>
 
     <para>
-      Note that <literal>%c</literal> and <literal>%a</literal> will only be provided during
-      <varname>bdr_failover</varname> events, which is what is of interest here.
+      Note that <literal>%c</literal> and <literal>%a</literal> are only provided with
+      particular failover events, in this case <varname>bdr_failover</varname>.
     </para>
     <para>
-      The provided sample script (`scripts/bdr-pgbouncer.sh`) is configured like
-      this:
+      The provided sample script (`scripts/bdr-pgbouncer.sh`) is configured as follows:
       <programlisting>
         event_notification_command='/path/to/bdr-pgbouncer.sh %n %e %s "%c" "%a"'</programlisting>
     </para>
     <para>
-      and parses the configures parameters like this:
+      and parses the placeholder parameters like this:
       <programlisting>
         NODE_ID=$1
         EVENT_TYPE=$2
@@ -252,12 +263,14 @@
         NEXT_CONNINFO=$4
         NEXT_NODE_NAME=$5</programlisting>
     </para>
-    <para>
-      The script also contains some hard-coded values about the <application>PgBouncer</application>
-      configuration for both nodes; these will need to be adjusted for your local environment
-      (ideally the scripts would be maintained as templates and generated by some
-      kind of provisioning system).
-    </para>
+    <note>
+      <para>
+        The sample script also contains some hard-coded values for the <application>PgBouncer</application>
+        configuration for both nodes; these will need to be adjusted for your local environment
+        (ideally the scripts would be maintained as templates and generated by some
+        kind of provisioning system).
+      </para>
+    </note>
 
     <para>
       The script performs following steps: