diff --git a/docs/3.x.x/en/advanced/hooks.md b/docs/3.x.x/en/advanced/hooks.md
index b5143babe3..6a27b5e0b0 100644
--- a/docs/3.x.x/en/advanced/hooks.md
+++ b/docs/3.x.x/en/advanced/hooks.md
@@ -2,9 +2,8 @@
 
 The hooks are modules that add functionality to the core. They are loaded during the server boot. For example, if your project needs to work with a SQL database, your will have to add the hook `strapi-bookshelf` to be able to connect your app with your database.
 
-
+**Path —** `./hooks/documentation/lib/index.js`.
 ```js
-
 const fs = require('fs');
 const path = require('path');
 
@@ -38,7 +37,16 @@ module.exports = strapi => {
       // it's just an example to tell you that you
       // run your business logic and when it's done
       // you just need to call the callback `cb`
-      generateDocumentation(path.resolve(process.cwd(), this.defaults.documentation.path), cb);
+      generateDocumentation(path.resolve(process.cwd(), this.defaults.documentation.path), function(err) {
+        if (err) {
+          // Error: it will display the error to the user
+          // and the hook won't be loaded.
+          return cb(err);
+        }
+
+        // Success.
+        cb();
+      });
     }
   };
 
@@ -46,8 +54,25 @@ module.exports = strapi => {
 };
 ```
 
+- `defaults` (object): Contains the defaults configurations. This object is merged to `strapi.config.hook.settings.**`.
+- `initialize` (function): Called during the server boot. The callback `cb` needs to be called. Otherwise, the hook won't be loaded.
+
 Every folder that follows this name pattern `strapi-*` in your `./node_modules` folder will be loaded as a hook. The hooks are accessible through the `strapi.hook` variable.
 
+## Structure
+
+A hook needs to follow the structure below:
+
+```
+/lib
+- index.js
+- LICENSE.md
+- package.json
+- README.md
+```
+
+The `index.js` is the entry point to your hook. It should look like the example above.
+
 ## Dependencies
 
 It happens that a hook has a dependency to another one. For example, the `strapi-bookshelf` has a dependency to `strapi-knex`. Without it, the `strapi-bookshelf` can't work correctly. It also means that the `strapi-knex` hook has to be loaded before.
diff --git a/docs/3.x.x/en/advanced/middlewares.md b/docs/3.x.x/en/advanced/middlewares.md
index 15a273ecbf..830a2eb2e0 100644
--- a/docs/3.x.x/en/advanced/middlewares.md
+++ b/docs/3.x.x/en/advanced/middlewares.md
@@ -2,8 +2,8 @@
 
 The middlewares are functions which are composed and executed in a stack-like manner upon request. If you are not familiar with the middleware stack in Koa, we highly recommend you to read the [Koa's documentation introduction](http://koajs.com/#introduction).
 
+**Path —** [`strapi/lib/middlewares/responseTime/index.js`](https://github.com/strapi/strapi/blob/master/packages/strapi/lib/middlewares/responseTime/index.js).
 ```js
-// X-Response-Time middleware
 module.exports = strapi => {
   return {
     defaults: {
@@ -30,6 +30,9 @@ module.exports = strapi => {
 };
 ```
 
+- `defaults` (object): Contains the defaults configurations. This object is merged to `strapi.config.middleware.settings.**`.
+- `initialize` (function): Called during the server boot. The callback `cb` needs to be called. Otherwise, the middleware won't be loaded into the stack.
+
 The core of Strapi embraces a small list of middlewares for performances, security and great error handling.
 
 - boom
@@ -55,6 +58,17 @@ The core of Strapi embraces a small list of middlewares for performances, securi
 
 > Note: The following middlewares cannot be disabled: responses, router, logger and boom.
 
+## Structure
+
+A middleware needs to follow the structure below:
+
+```
+/lib
+- index.js
+```
+
+The `index.js` is the entry point to your middleware. It should look like the example above.
+
 ## Custom middlewares
 
 The framework allows the application to override the default middlewares and add new ones. You have to create a `./middlewares` folder at the root of your project and put the middlewares into it.