diff --git a/docs/reference/glib/running.xml b/docs/reference/glib/running.xml
index ef536f440..8e4ffeca3 100644
--- a/docs/reference/glib/running.xml
+++ b/docs/reference/glib/running.xml
@@ -122,13 +122,15 @@ How to run and debug your GLib application
       <varlistentry>
         <term>fatal-warnings</term>
         <listitem><para>Causes GLib to abort the program at the first call
-           to g_warning() or g_critical().</para>
+           to g_warning() or g_critical().  Use of this flag is not
+           recommended except when debugging.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term>fatal-criticals</term>
         <listitem><para>Causes GLib to abort the program at the first call
-           to g_critical().</para>
+           to g_critical().  This flag can be useful during debugging and
+           testing.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
diff --git a/glib/gmessages.c b/glib/gmessages.c
index cbaed5da9..fb1108f9b 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -387,6 +387,16 @@ myInvalidParameterHandler(const wchar_t *expression,
  * preferred for that instead, as it allows calling functions to perform actions
  * conditional on the type of error.
  *
+ * Warning messages are intended to be used in the event of unexpected
+ * external conditions (system misconfiguration, missing files,
+ * other trusted programs violating protocol, invalid contents in
+ * trusted files, etc.)
+ *
+ * If attempting to deal with programmer errors (for example, incorrect function
+ * parameters) then you should use %G_LOG_LEVEL_CRITICAL instead.
+ *
+ * g_warn_if_reached() and g_warn_if_fail() log at %G_LOG_LEVEL_WARNING.
+ *
  * You can make warnings fatal at runtime by setting the `G_DEBUG`
  * environment variable (see
  * [Running GLib Applications](glib-running.html)):
@@ -413,13 +423,16 @@ myInvalidParameterHandler(const wchar_t *expression,
  *     into the format string (as with printf())
  *
  * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL).
- * It's more or less application-defined what constitutes
- * a critical vs. a regular warning. You could call
- * g_log_set_always_fatal() to make critical warnings exit
- * the program, then use g_critical() for fatal errors, for
- * example.
  *
- * You can also make critical warnings fatal at runtime by
+ * Critical warnings are intended to be used in the event of an error
+ * that originated in the current process (a programmer error).
+ * Logging of a critical error is by definition an indication of a bug
+ * somewhere in the current program (or its libraries).
+ *
+ * g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
+ * g_return_val_if_reached() log at %G_LOG_LEVEL_CRITICAL.
+ *
+ * You can make critical warnings fatal at runtime by
  * setting the `G_DEBUG` environment variable (see
  * [Running GLib Applications](glib-running.html)):
  *
@@ -427,6 +440,8 @@ myInvalidParameterHandler(const wchar_t *expression,
  *   G_DEBUG=fatal-warnings gdb ./my-program
  * ]|
  *
+ * You can also use g_log_set_always_fatal().
+ *
  * Any unrelated failures can be skipped over in
  * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
  *
@@ -778,6 +793,11 @@ g_log_set_always_fatal (GLogLevelFlags fatal_mask)
  * g_log_set_writer_func(). See
  * [Using Structured Logging][using-structured-logging].
  *
+ * This function is mostly intended to be used with
+ * %G_LOG_LEVEL_CRITICAL.  You should typically not set
+ * %G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or
+ * %G_LOG_LEVEL_DEBUG as fatal except inside of test programs.
+ *
  * Returns: the old fatal mask for the log domain
  */
 GLogLevelFlags