diff --git a/doc/api/README.md b/doc/api/README.md
index 09c52350f3fcaf5eacfe2b334a8dfefb380c1f6b..4ef4c031bc24f3aac3624d9238e0a5236076fd65 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -13,7 +13,7 @@
 + [Merge Requests](merge_requests.md)
 + [Issues](issues.md)
 + [Milestones](milestones.md)
-+ [Notes](notes.md)
++ [Notes](notes.md) (comments)
 + [Deploy Keys](deploy_keys.md)
 + [System Hooks](system_hooks.md)
 + [Groups](groups.md)
diff --git a/doc/api/issues.md b/doc/api/issues.md
index 823b72f5b0c34d00c7beec2eadd8c9b70414dfe4..d18506f9ce6a6c4836a4305087f0a8f16913393e 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -193,3 +193,7 @@ Parameters:
 
 + `id` (required) - The project ID
 + `issue_id` (required) - The ID of the issue
+
+## Comments on issues
+
+Comments are done via the notes resource.
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 2996f609d43e6527024179745d6c44e0752c95ce..d5b106729c94546b049018f6cbe18530f8c4f690 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -258,3 +258,7 @@ Parameters:
   }
 ]
 ```
+
+## Comments on issues
+
+Comments are done via the notes resource.
diff --git a/doc/api/notes.md b/doc/api/notes.md
index b15ebdd2bac0edae36ef7b120d7cc2e1a6140c89..e9ad6e00c73164c1c009e0afa8e43045f396ba4e 100644
--- a/doc/api/notes.md
+++ b/doc/api/notes.md
@@ -1,3 +1,5 @@
+Notes can be wall notes or comments on snippets, issues or merge requests.
+
 ## Wall
 
 ### List project wall notes