diff --git a/Documentation/Books/Users/Upgrading/Upgrading28.mdpp b/Documentation/Books/Users/Upgrading/Upgrading28.mdpp
index aedce83787..11692bd3f5 100644
--- a/Documentation/Books/Users/Upgrading/Upgrading28.mdpp
+++ b/Documentation/Books/Users/Upgrading/Upgrading28.mdpp
@@ -107,3 +107,59 @@ above in the graphical front end. You have to replace `"root"` with
 a user name and `""` with a password that is valid for authentication
 with the cluster.
 
+!SECTION Upgrading Foxx apps generated by ArangoDB 2.7 and earlier
+
+The implementation of the `require` function used to import modules in
+ArangoDB and Foxx [has changed](./UpgradingChanges28.md#module-resolution)
+in order to improve compatibility with Node.js modules.
+
+Given an app/service with the following layout:
+
+* manifest.json
+* controllers/
+  * todos.js
+* models/
+  * todo.js
+* repositories/
+  * todos.js
+* node_modules/
+  * models/
+    * todo.js
+
+The file `controllers/todos.js` would previously contain the following
+`require` calls:
+
+```js
+var _ = require('underscore');
+var joi = require('joi');
+var Foxx = require('org/arangodb/foxx');
+var ArangoError = require('org/arangodb').ArangoError;
+var Todos = require('repositories/todos'); // <-- !
+var Todo = require('models/todo'); // <-- !
+```
+
+The require paths `repositories/todos` and `models/todo` were previously
+resolved locally as relative to the app root.
+
+Starting with 2.8 these paths would instead be resolved as relative to
+the `node_modules` folder or the global ArangoDB module paths before being
+resolved locally as a fallback.
+
+In the given example layout the app would break in 2.8 because the module
+name `models/todo` would always resolve to `node_modules/models/todo.js`
+(which previously would have been ignored) instead of the local `models/todo.js`.
+
+In order to make sure the app still works in 2.8, the require calls in
+`controllers/todos.js` would need to be adjusted to look like this:
+
+```js
+var _ = require('underscore');
+var joi = require('joi');
+var Foxx = require('org/arangodb/foxx');
+var ArangoError = require('org/arangodb').ArangoError;
+var Todos = require('../repositories/todos'); // <-- !
+var Todo = require('../models/todo'); // <-- !
+```
+
+Note that the old "global" style require calls may still work in 2.8 but
+may break unexpectedly if modules with matching names are installed globally.
diff --git a/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp b/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp
index 64ee4dda5b..a841b2d4aa 100644
--- a/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp
+++ b/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp
@@ -95,7 +95,7 @@ file paths first, leading to problems when local files used the same names as ot
 modules (e.g. a local file `chai.js` would cause problems when trying to load the
 `chai` module installed in `node_modules`).
 
-For more information see the [blog announcement of this change](https://www.arangodb.com/blog/).
+For more information see the [blog announcement of this change](https://www.arangodb.com/2015/11/foxx-module-resolution-will-change-in-2-8/) and the [upgrade guide](./Upgrading28.md#upgrading-foxx-apps-generated-by-arangodb-27-and-earlier).
 
 !SUBSECTION Module `org/arangodb/request`