diff --git a/docs/building.html b/docs/building.html
index fe2de4ffd..75b226f68 100644
--- a/docs/building.html
+++ b/docs/building.html
@@ -458,8 +458,13 @@ defines you can use to control the build.</p>
 <tr><td><tt class="docutils literal"><span class="pre">NDEBUG</span></tt></td>
 <td>If you define this macro, all asserts,
 invariant checks and general debug code will be
-removed. This option takes precedence over
-other debug settings.</td>
+removed. Since there is quite a lot of code in
+in header files in libtorrent, it may be
+important to define the symbol consistently
+across compilation units, including the clients
+files. Potential problems is different
+compilation units having different views of
+structs and class layouts and sizes.</td>
 </tr>
 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_LOGGING</span></tt></td>
 <td>This macro will enable logging of the session
diff --git a/docs/building.rst b/docs/building.rst
index fbe545ab9..0bf631c9b 100644
--- a/docs/building.rst
+++ b/docs/building.rst
@@ -442,8 +442,13 @@ defines you can use to control the build.
 +=================================+=================================================+
 | ``NDEBUG``                      | If you define this macro, all asserts,          |
 |                                 | invariant checks and general debug code will be |
-|                                 | removed. This option takes precedence over      |
-|                                 | other debug settings.                           |
+|                                 | removed. Since there is quite a lot of code in  |
+|                                 | in header files in libtorrent, it may be        |
+|                                 | important to define the symbol consistently     |
+|                                 | across compilation units, including the clients |
+|                                 | files. Potential problems is different          |
+|                                 | compilation units having different views of     |
+|                                 | structs and class layouts and sizes.            |
 +---------------------------------+-------------------------------------------------+
 | ``TORRENT_LOGGING``             | This macro will enable logging of the session   |
 |                                 | events, such as tracker announces and incoming  |