diff --git a/doc/hacking.txt b/doc/hacking.txt
index ab99a62c..00ab4503 100644
--- a/doc/hacking.txt
+++ b/doc/hacking.txt
@@ -618,6 +618,22 @@ typedef int (some_func_T)(void *);
 typedef long long our_long_T;
 -------------------------------------------------------------------------------
 
+Please use mode_t and S_I???? macros instead of numeric modes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.Use:
+-------------------------------------------------------------------------------
+mode_t mode = S_IRWXU | S_IRGRP | S_IROTH;
+-------------------------------------------------------------------------------
+
+.Instead of:
+-------------------------------------------------------------------------------
+int mode = 0744;
+-------------------------------------------------------------------------------
+
+Note that S_IREAD, S_IWRITE and S_IEXEC are obsolete, you should use S_IRUSR,
+S_IWUSR, S_IXUSR instead.
+
 
 Patches
 ~~~~~~~