Documentation language

docs/dynamic_configuration.rst

@@ -4,21 +4,21 @@ Patroni configuration
 Patroni configuration is stored in the DCS (Distributed Configuration Store). There are 3 types of configuration:
 
 - Dynamic configuration.
-	Those options can be set in DCS at any time. If the options changed are not part of the startup configuration,
+	These options can be set in DCS at any time. If the options changed are not part of the startup configuration,
 	they are applied asynchronously (upon the next wake up cycle) to every node, which gets subsequently reloaded.
 	If the node requires a restart to apply the configuration (for options with context postmaster, if their values
 	have changed), a special flag, ``pending_restart`` indicating this, is set in the members.data JSON.
 	Additionally, the node status also indicates this, by showing ``"restart_pending": true``.
 
 - Local `configuration <https://github.com/zalando/patroni/blob/master/docs/SETTINGS.rst>`__ (patroni.yml).
-	Those options are defined in the configuration file and take precedence over dynamic configuration.
+	These options are defined in the configuration file and take precedence over dynamic configuration.
 	patroni.yml could be changed and reload in runtime (without restart of Patroni) by sending SIGHUP to the Patroni process or by performing ``POST /reload`` REST-API request.
 
-- Environment `configuration <https://github.com/zalando/patroni/blob/master/docs/ENVIRONMENT.rst>`
+- Environment `configuration <https://github.com/zalando/patroni/blob/master/docs/ENVIRONMENT.rst>`__ .
 	It is possible to set/override some of the "Local" configuration parameters with environment variables.
-	Environment configuration is very useful when you are running in dynamic environment and you don't know some of the parameters in advance (for example it's not possible to know you external IP address when you are running inside ``docker``).
+	Environment configuration is very useful when you are running in a dynamic environment and you don't know some of the parameters in advance (for example it's not possible to know you external IP address when you are running inside ``docker``).
 
-Some of PostgreSQL parameters must be set to the same value on master and replicas and therefore controlled only via "Dynamic configuration". Any attemt to change them via "Local configuration" are blocked:
+Some of the PostgreSQL parameters must be set to the same value on master and replicas and therefore are only controlled via "Dynamic configuration". Any attemt to change them via "Local configuration" are ignored:
 
 - max_connections: 100
 - max_locks_per_transaction: 64
@@ -28,20 +28,22 @@ Some of PostgreSQL parameters must be set to the same value on master and replic
 - wal_log_hints: on
 - track_commit_timestamp: off
 
-Although following parameters are not necessarily must be the same on master and replicas, but it is better to have them eqals, therefore they are also controlled by Patroni and can be set only via Dynamic configuration.
+For the following parameters it is not essential for them to be equal on the master and the replica, it is preferred to configure the uniformly. Therefore they are also controlled by Patroni and can be set only via Dynamic configuration.
+
 - max_wal_senders: 5
 - max_replication_slots: 5
 - wal_keep_segments: 8
 
-Important! Patroni does some simple checks of new values obtained from DCS before applying them. Above lists containing some sane default values and it is not allowed to set new value smaller.
+These parameters are validated to ensure they are sane, or meet a minimum value.
 
 There are some other PostgreSQL parameters controlled by Patroni:
+
 - listen_addresses - is set either from ``postgresql.listen`` or from ``PATRONI_POSTGRESQL_LISTEN`` environment variable
 - port - is set either from ``postgresql.listen`` or from ``PATRONI_POSTGRESQL_LISTEN`` environment variable
 - cluster_name - is set either from ``scope`` or from ``PATRRONI_SCOPE`` environment variable
 - hot_standby: on
 
-To be on the safe side parameters from the above lists are not written into ``postgresql.conf``, but passed as a list of arguments to the ``pg_ctl start`` what makes it not possible to change them even with 'ALTER SYSTEM'
+To be on the safe side parameters from the above lists are not written into ``postgresql.conf``, but passed as a list of arguments to the ``pg_ctl start`` which gives the the highest precedence, even above `ALTER SYSTEM <https://www.postgresql.org/docs/current/static/sql-altersystem.html>`__
 
 
 When applying the local or dynamic configuration options, the following actions are taken:
@@ -55,7 +57,7 @@ When applying the local or dynamic configuration options, the following actions
 - If some of the options that require restart are changed (we should look at the context in pg_settings and at the actual
   values of those options), a pending_restart flag of a given node is set. This flag is reset on any restart.
 
-Parameters would be applied in the following order (run-time are given the highest priority):
+The parameters would be applied in the following order (run-time are given the highest priority):
 
 1. load parameters from file `postgresql.base.conf`
 2. load parameters from file `postgresql.conf`
@@ -73,15 +75,15 @@ Also, the following patroni configuration options can be changed only dynamicall
 - maximum_lag_on_failover: 1048576
 - postgresql.use_slots: true
 
-Upon changing those options, Patroni should read the relevant section of the configuration stored in DCS and change their
+Upon changing these options, Patroni will read the relevant section of the configuration stored in DCS and change its
 run-time values.
 
-Patroni nodes are dumping the state of the DCS options to disk upon every change of the configuration into file ``patroni.dynamic.json`` located in the postgres data directory. Only master is allowed to restore those options from the on-disk dump if those are completely absent from the DCS or invalid.
+Patroni nodes are dumping the state of the DCS options to disk upon for every change of the configuration into the file ``patroni.dynamic.json`` located in the postgres data directory. Only the master is allowed to restore these options from the on-disk dump if these are completely absent from the DCS or if they are invalid.
 
 REST API
 ========
 
-We are providing REST API endpoint for working with dynamic configuration.
+We provide a REST API endpoint for working with dynamic configuration.
 
 GET /config
 -----------
@@ -139,9 +141,9 @@ Patch existing configuration.
 	  }
 	}
 
-Above REST API call patches existing configuration and returns the new configuration.
+The above REST API call patches the existing configuration and returns the new configuration.
 
-Let's check that node processed this configuration. First of all it should start printing logs lines every 5 seconds (loop_wait=5). Change of "max_connections" requires restart, so "restart_pending" flag should be exposed:
+Let's check that the node processed this configuration. First of all it should start printing log lines every 5 seconds (loop_wait=5). The change of "max_connections" requires a restart, so the "restart_pending" flag should be exposed:
 
 .. code-block:: bash
 
@@ -191,12 +193,12 @@ If you want to remove (reset) some setting just patch it with ``null``:
 	  }
 	}
 
-Above call removes ``postgresql.parameters.max_connections`` from dynaminc configuration.
+Above call removes ``postgresql.parameters.max_connections`` from the dynamic configuration.
 
 PUT /config
 -----------
 
-It's also possible to perform the full rewrite of existing dynamic configuration unconditionally:
+It's also possible to perform the full rewrite of an existing dynamic configuration unconditionally:
 
 .. code-block:: bash