diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md
index b605f3540f3847c74ad3160637274018ce5408ba..dc036d7e27fce417c1cc27dab18f620e146cfee6 100644
--- a/doc/api/system_hooks.md
+++ b/doc/api/system_hooks.md
@@ -1,18 +1,24 @@
 # System hooks
 
-All methods require admin authorization.
+All methods require administrator authorization.
 
 The URL endpoint of the system hooks can also be configured using the UI in
-the admin area under hooks(`/admin/hooks`).
+the admin area under **Hooks** (`/admin/hooks`).
+
+Read more about [system hooks](../system_hooks/system_hooks.md).
 
 ## List system hooks
 
 Get a list of all system hooks.
 
+---
+
 ```
 GET /hooks
 ```
 
+Example request:
+
 ```bash
 curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks
 ```
@@ -31,6 +37,10 @@ Example response:
 
 ## Add new system hook
 
+Add a new system hook.
+
+---
+
 ```
 POST /hooks
 ```
@@ -39,6 +49,8 @@ POST /hooks
 | --------- | ---- | -------- | ----------- |
 | `url` | string | yes | The hook URL |
 
+Example request:
+
 ```bash
 curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/hooks?url=https://gitlab.example.com/hook"
 ```
@@ -65,6 +77,8 @@ GET /hooks/:id
 | --------- | ---- | -------- | ----------- |
 | `id` | integer | yes | The ID of the hook |
 
+Example request:
+
 ```bash
 curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2
 ```
@@ -85,8 +99,12 @@ Example response:
 ## Delete system hook
 
 Deletes a system hook. This is an idempotent API function and returns `200 OK`
-even if the hook is not available. If the hook is deleted a JSON object is
-returned.
+even if the hook is not available.
+
+If the hook is deleted, a JSON object is returned. An error is raised if the
+hook is not found.
+
+---
 
 ```
 DELETE /hooks/:id
@@ -96,6 +114,8 @@ DELETE /hooks/:id
 | --------- | ---- | -------- | ----------- |
 | `id` | integer | yes | The ID of the hook |
 
+Example request:
+
 ```bash
 curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2
 ```