diff --git a/README b/README
index 66462c8a..7ae9bb2e 100644
--- a/README
+++ b/README
@@ -115,6 +115,17 @@ docs/
 	reference documenation in docs/reference/ You need to have the gtk doc
 	tools installed to generate this API documentation.
 
+	Note that the currrent gtk-docs integration sucks a bit wrt regenerating
+	the html files. You need at least
+
+	$ make clean -C docs && make -C docs
+
+	to regenerate them on any change. If you've added/changed/removed a
+	symbol or anything else that changes the overall structure or indexes,
+	you need a full rebuild:
+
+	$ git clean -dfx && ./autogen.sh --enable-gtk-doc && make -C docs
+
 DEPENDENCIES
 	This is a non-exchaustive list of package dependencies required for
 	building everything: