Document the new feature

docs/admin/deployment.rst

@@ -284,6 +284,21 @@ you create:
    Optional. Set your `SYSTRAN Translate API key` to use machine translation
    by SYSTRAN.
 
+``THROTTLE_ENABLED``
+   Optional. Enables traffic throttling based on IP address (default: ``False``).
+
+``THROTTLE_MAX_COUNT``
+   Optional. Maximum number of requests allowed in ``THROTTLE_OBSERVATION_PERIOD``
+   (default: ``300``).
+
+``THROTTLE_OBSERVATION_PERIOD``
+   Optional. A period (in seconds) in which ``THROTTLE_MAX_COUNT`` requests are
+   allowed. (default: ``60``). If longer than ``THROTTLE_BLOCK_DURATION``,
+   ``THROTTLE_BLOCK_DURATION`` will be used.
+
+``THROTTLE_BLOCK_DURATION``
+   Optional. A duration (in seconds) for which IPs are blocked (default: ``600``).
+
 ``TZ``
    Timezone for the dynos that will run the app. Pontoon operates in UTC, so set
    this to ``UTC``.

docs/admin/maintenance.rst

@@ -47,8 +47,12 @@ In a distributed denial-of-service attack (`DDoS`_ attack), the incoming traffic
 flooding the victim originates from many different sources. This stops everyone
 else from accessing the website as there is too much traffic flowing to it.
 
-One way to mitigate DDoS attacks is to identify the IP addresses of the
-attackers (see the handy `IP detection script`_ to help with that) and block them.
+One way to mitigate DDoS attacks is to enable traffic throttling. Set the
+`THROTTLE_ENABLED` environment variable to True and configure other THROTTLE*
+variables to limit the number of requests per period from a single IP address.
+
+A more involved but also more controlled approach is to identify the IP addresses of
+the attackers (see the handy `IP detection script`_ to help with that) and block them.
 Find the attacking IP addresses in the Log Management Add-On (Papertrail)
 and add them to the BLOCKED_IPs config variable in Heroku Settings.