diff --git a/debian/changelog b/debian/changelog
index a6d88906ac..a0af2b78a8 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,13 @@
+matrix-synapse-py3 (1.xx.0) stable; urgency=medium
+
+ [ Synapse Packaging team ]
+ * New synapse release 1.xx.0.
+
+ [ Aaron Raimist ]
+ * Fix outdated documentation for SYNAPSE_CACHE_FACTOR
+
+ -- Synapse Packaging team <packages@matrix.org> XXXXX
+
matrix-synapse-py3 (1.18.0) stable; urgency=medium
* New synapse release 1.18.0.
diff --git a/debian/matrix-synapse.default b/debian/matrix-synapse.default
index 65dc2f33d8..f402d73bbf 100644
--- a/debian/matrix-synapse.default
+++ b/debian/matrix-synapse.default
@@ -1,2 +1,2 @@
# Specify environment variables used when running Synapse
-# SYNAPSE_CACHE_FACTOR=1 (default)
+# SYNAPSE_CACHE_FACTOR=0.5 (default)
diff --git a/debian/synctl.ronn b/debian/synctl.ronn
index a73c832f62..1bad6094f3 100644
--- a/debian/synctl.ronn
+++ b/debian/synctl.ronn
@@ -46,19 +46,20 @@ Configuration file may be generated as follows:
## ENVIRONMENT
* `SYNAPSE_CACHE_FACTOR`:
- Synapse's architecture is quite RAM hungry currently - a lot of
- recent room data and metadata is deliberately cached in RAM in
- order to speed up common requests. This will be improved in
- future, but for now the easiest way to either reduce the RAM usage
- (at the risk of slowing things down) is to set the
- SYNAPSE_CACHE_FACTOR environment variable. Roughly speaking, a
- SYNAPSE_CACHE_FACTOR of 1.0 will max out at around 3-4GB of
- resident memory - this is what we currently run the matrix.org
- on. The default setting is currently 0.1, which is probably around
- a ~700MB footprint. You can dial it down further to 0.02 if
- desired, which targets roughly ~512MB. Conversely you can dial it
- up if you need performance for lots of users and have a box with a
- lot of RAM.
+ Synapse's architecture is quite RAM hungry currently - we deliberately
+ cache a lot of recent room data and metadata in RAM in order to speed up
+ common requests. We'll improve this in the future, but for now the easiest
+ way to either reduce the RAM usage (at the risk of slowing things down)
+ is to set the almost-undocumented ``SYNAPSE_CACHE_FACTOR`` environment
+ variable. The default is 0.5, which can be decreased to reduce RAM usage
+ in memory constrained enviroments, or increased if performance starts to
+ degrade.
+
+ However, degraded performance due to a low cache factor, common on
+ machines with slow disks, often leads to explosions in memory use due
+ backlogged requests. In this case, reducing the cache factor will make
+ things worse. Instead, try increasing it drastically. 2.0 is a good
+ starting value.
## COPYRIGHT
|
