diff --git a/docs/usermanual-fonts-and-faces.xml b/docs/usermanual-fonts-and-faces.xml
index 6dade2f79..ccf123d48 100644
--- a/docs/usermanual-fonts-and-faces.xml
+++ b/docs/usermanual-fonts-and-faces.xml
@@ -467,13 +467,24 @@
range actually implemented in the font's variation axis. After
all, a font might only provide lighter-than-regular weights, and
setting a heavier value on the wght axis will
- not change that.
+ not change that.
Once your variation settings are specified on your font object,
however, shaping with a variable font is just like shaping a
static font.
+
+ In addition to providing the variation axes themselves, fonts may also
+ pre-define certain variation coordinates as named instances. HarfBuzz
+ makes these coordinates (and their associated names) available via
+ hb_ot_var_named_instance_get_design_coords() and
+ hb_ot_var_named_instance_get_subfamily_name_id().
+
+
+ Applications should treat named instances like multiple independent,
+ static fonts.
+