diff --git a/glib/docs.c b/glib/docs.c
index 14c47ad77..9883cfbf7 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -2020,6 +2020,22 @@
  *
  * This macro is defined only on UNIX. So you can bracket
  * UNIX-specific code in "\#ifdef G_OS_UNIX".
+ *
+ * To detect whether to compile features that require a specific kernel
+ * or operating system, check for the appropriate OS-specific predefined
+ * macros instead, for example:
+ *
+ * - Linux kernel (any libc, including glibc, musl or Android): `\#ifdef __linux__`
+ * - Linux kernel and GNU user-space: `\#if defined(__linux__) && defined(__GLIBC__)`
+ * - FreeBSD kernel (any libc, including glibc): `\#ifdef __FreeBSD_kernel__`
+ * - FreeBSD kernel and user-space: `\#ifdef __FreeBSD__`
+ *
+ * See <https://sourceforge.net/p/predef/wiki/OperatingSystems/> for more.
+ *
+ * GLib defines OS-detection macros for some categories of systems
+ * that can be less straightforward to detect, such as %G_OS_DARWIN, but
+ * intentionally does not provide its own equivalents of macros like
+ * `__linux__`.
  */
 
 /**