diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c
index f0cc8ea6ff..4dec0530ce 100644
--- a/gtk/gtkcheckbutton.c
+++ b/gtk/gtkcheckbutton.c
@@ -77,6 +77,11 @@
  *
  * To add a `GtkCheckButton` to a group, use [method@Gtk.CheckButton.set_group].
  *
+ * When the code must keep track of the state of a group of radio buttons, it
+ * is recommended to keep track of such state through a stateful
+ * `GAction` with a target for each button. Using the `toggled` signals to keep
+ * track of the group changes and state is discouraged.
+ *
  * # CSS nodes
  *
  * ```