diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md
index 41e39c31069..92936a277ac 100644
--- a/doc/api/award_emoji.md
+++ b/doc/api/award_emoji.md
@@ -1,19 +1,26 @@
 # Award Emoji API
 
-> [Introduced][ce-4575] in GitLab 8.9, Snippet support in 8.12
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575) in GitLab 8.9. Snippet support added in 8.12.
 
+An [awarded emoji](../user/award_emojis.md) tells a thousand words.
 
-An awarded emoji tells a thousand words, and can be awarded on issues, merge
-requests, snippets, and notes/comments. Issues, merge requests, snippets, and notes are further called
-`awardables`.
+Emoji can be awarded on the following (known as "awardables"):
+
+- [Issues](../user/project/issues/index.md) ([API](issues.md)).
+- [Merge requests](../user/project/merge_requests/index.md) ([API](merge_requests.md)).
+- [Snippets](../user/snippets.md) ([API](snippets.md)).
+
+Emoji can also [be awarded](../user/award_emojis.html#award-emoji-for-comments) on comments (also known as notes). See also [Notes API](notes.md).
 
 ## Issues, merge requests, and snippets
 
+See [Award Emoji on Comments](#award-emoji-on-comments) for information on using these endpoints with comments.
+
 ### List an awardable's award emoji
 
-Gets a list of all award emoji
+Get a list of all award emoji for a specified awardable.
 
-```
+```text
 GET /projects/:id/issues/:issue_iid/award_emoji
 GET /projects/:id/merge_requests/:merge_request_iid/award_emoji
 GET /projects/:id/snippets/:snippet_id/award_emoji
@@ -21,16 +28,18 @@ GET /projects/:id/snippets/:snippet_id/award_emoji
 
 Parameters:
 
-| Attribute      | Type    | Required | Description                                                                 |
-| ---------      | ----    | -------- | -----------                                                                 |
-| `id`           | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user                                                         |
-| `awardable_id` | integer | yes      | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
+| Attribute      | Type           | Required | Description                                                                  |
+|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `awardable_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
 
-```bash
+Example request:
+
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji
 ```
 
-Example Response:
+Example response:
 
 ```json
 [
@@ -71,9 +80,9 @@ Example Response:
 
 ### Get single award emoji
 
-Gets a single award emoji from an issue, snippet, or merge request.
+Get a single award emoji from an issue, snippet, or merge request.
 
-```
+```text
 GET /projects/:id/issues/:issue_iid/award_emoji/:award_id
 GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
 GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
@@ -81,17 +90,19 @@ GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
 
 Parameters:
 
-| Attribute      | Type    | Required | Description                                                                 |
-| ---------      | ----    | -------- | -----------                                                                 |
-| `id`           | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `awardable_id` | integer | yes      | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
-| `award_id`     | integer | yes      | The ID of the award emoji                                                   |
+| Attribute      | Type           | Required | Description                                                                  |
+|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `awardable_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
+| `award_id`     | integer        | yes      | ID of the award emoji.                                                       |
 
-```bash
+Example request:
+
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1
 ```
 
-Example Response:
+Example response:
 
 ```json
 {
@@ -114,9 +125,9 @@ Example Response:
 
 ### Award a new emoji
 
-This end point creates an award emoji on the specified resource
+Create an award emoji on the specified awardable.
 
-```
+```text
 POST /projects/:id/issues/:issue_iid/award_emoji
 POST /projects/:id/merge_requests/:merge_request_iid/award_emoji
 POST /projects/:id/snippets/:snippet_id/award_emoji
@@ -124,13 +135,13 @@ POST /projects/:id/snippets/:snippet_id/award_emoji
 
 Parameters:
 
-| Attribute      | Type    | Required | Description                                                                 |
-| ---------      | ----    | -------- | -----------                                                                 |
-| `id`           | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `awardable_id` | integer | yes      | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
-| `name`         | string  | yes      | The name of the emoji, without colons                                       |
+| Attribute      | Type           | Required | Description                                                                  |
+|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `awardable_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
+| `name`         | string         | yes      | Name of the emoji without colons.                                            |
 
-```bash
+```sh
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish
 ```
 
@@ -157,10 +168,12 @@ Example Response:
 
 ### Delete an award emoji
 
-Sometimes its just not meant to be, and you'll have to remove your award. Only available to
-admins or the author of the award.
+Sometimes it's just not meant to be and you'll have to remove the award.
 
-```
+NOTE: **Note:**
+Only available to administrators or the author of the award.
+
+```text
 DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id
 DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
 DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
@@ -168,43 +181,47 @@ DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
 
 Parameters:
 
-| Attribute   | Type    | Required | Description                 |
-| ---------   | ----    | -------- | -----------                 |
-| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
-| `issue_iid` | integer | yes      | The internal ID of an issue |
-| `award_id`  | integer | yes      | The ID of an award_emoji    |
+| Attribute      | Type           | Required | Description                                                                  |
+|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `id`           | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `awardable_id` | integer        | yes      | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable.     |
+| `award_id`     | integer        | yes      | ID of an award emoji.                                                        |
 
-```bash
+```sh
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344
 ```
 
-## Award Emoji on Notes
+## Award Emoji on Comments
 
-The endpoints documented above are available for Notes as well. Notes
-are a sub-resource of Issues, Merge Requests, or Snippets. The examples below
-describe working with Award Emoji on notes for an Issue, but can be
-easily adapted for notes on a Merge Request.
+Comments (also known as notes) are a sub-resource of issues, merge requests, and snippets.
 
-### List a note's award emoji
+NOTE: **Note:**
+The examples below describe working with award emoji on comments for an issue, but can be
+easily adapted for comments on a merge request.
 
-```
+### List a comment's award emoji
+
+Get all award emoji for a comment (note).
+
+```text
 GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
 ```
 
 Parameters:
 
-| Attribute   | Type    | Required | Description                 |
-| ---------   | ----    | -------- | -----------                 |
-| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `issue_iid` | integer | yes      | The internal ID of an issue |
-| `note_id`   | integer | yes      | The ID of a note            |
+| Attribute   | Type           | Required | Description                                                                  |
+|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
+| `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
 
+Example request:
 
-```bash
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji
 ```
 
-Example Response:
+Example response:
 
 ```json
 [
@@ -227,26 +244,30 @@ Example Response:
 ]
 ```
 
-### Get single note's award emoji
+### Get an award emoji for a comment
 
-```
+Get a single award emoji for a comment (note).
+
+```text
 GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
 ```
 
 Parameters:
 
-| Attribute   | Type    | Required | Description                 |
-| ---------   | ----    | -------- | -----------                 |
-| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
-| `issue_iid` | integer | yes      | The internal ID of an issue |
-| `note_id`   | integer | yes      | The ID of a note            |
-| `award_id`  | integer | yes      | The ID of the award emoji   |
+| Attribute   | Type           | Required | Description                                                                  |
+|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
+| `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
+| `award_id`  | integer        | yes      | ID of the award emoji.                                                       |
 
-```bash
+Example request:
+
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2
 ```
 
-Example Response:
+Example response:
 
 ```json
 {
@@ -267,26 +288,30 @@ Example Response:
 }
 ```
 
-### Award a new emoji on a note
+### Award a new emoji on a comment
 
-```
+Create an award emoji on the specified comment (note).
+
+```text
 POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
 ```
 
 Parameters:
 
-| Attribute   | Type    | Required | Description                           |
-| ---------   | ----    | -------- | -----------                           |
-| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `issue_iid` | integer | yes      | The internal ID of an issue           |
-| `note_id`   | integer | yes      | The ID of a note                      |
-| `name`      | string  | yes      | The name of the emoji, without colons |
+| Attribute   | Type           | Required | Description                                                                  |
+|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
+| `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
+| `name`      | string         | yes      | Name of the emoji without colons.                                            |
 
-```bash
+Example request:
+
+```sh
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji?name=rocket
 ```
 
-Example Response:
+Example response:
 
 ```json
 {
@@ -307,26 +332,28 @@ Example Response:
 }
 ```
 
-### Delete an award emoji
+### Delete an award emoji from a comment
 
-Sometimes its just not meant to be, and you'll have to remove your award. Only available to
-admins or the author of the award.
+Sometimes it's just not meant to be and you'll have to remove the award.
 
-```
+NOTE: **Note:**
+Only available to administrators or the author of the award.
+
+```text
 DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
 ```
 
 Parameters:
 
-| Attribute   | Type    | Required | Description                 |
-| ---------   | ----    | -------- | -----------                 |
-| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
-| `issue_iid` | integer | yes      | The internal ID of an issue |
-| `note_id`   | integer | yes      | The ID of a note            |
-| `award_id`  | integer | yes      | The ID of an award_emoji    |
+| Attribute   | Type           | Required | Description                                                                  |
+|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `issue_iid` | integer        | yes      | Internal ID of an issue.                                                     |
+| `note_id`   | integer        | yes      | ID of a comment (note).                                                      |
+| `award_id`  | integer        | yes      | ID of an award_emoji.                                                        |
 
-```bash
+Example request:
+
+```sh
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345
 ```
-
-[ce-4575]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575
diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md
index 93be3da44d4..e4fd08a582c 100644
--- a/doc/user/award_emojis.md
+++ b/doc/user/award_emojis.md
@@ -1,24 +1,24 @@
 # Award emoji
 
-> **Notes:**
-> - First [introduced][1825] in GitLab 8.2.
-> - GitLab 9.0 [introduced][ce-9570] the usage of native emojis if the platform
+> - First [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825) in GitLab 8.2.
+> - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570) the usage of native emoji if the platform
 >  supports them and falls back to images or CSS sprites. This change greatly
->  improved the award emoji performance overall.
+>  improved award emoji performance overall.
 
 When you're collaborating online, you get fewer opportunities for high-fives
-and thumbs-ups. Emoji can be awarded to issues, merge requests, snippets, and
-virtually everywhere where you can have a discussion.
+and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md),
+[snippets](snippets.md), and anywhere you can have a discussion.
 
 ![Award emoji](img/award_emoji_select.png)
 
 Award emoji make it much easier to give and receive feedback without a long
-comment thread. Comments that are only emoji will automatically become
-award emoji.
+comment thread.
+
+For information on the relevant API, see [Award Emoji API](../api/award_emoji.md).
 
 ## Sort issues and merge requests on vote count
 
-> [Introduced][2871] in GitLab 8.5.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781) in GitLab 8.5.
 
 You can quickly sort issues and merge requests by the number of votes they
 have received. The sort options can be found in the dropdown menu as "Most
@@ -32,20 +32,16 @@ downvotes.
 
 ## Award emoji for comments
 
-> [Introduced][4291] in GitLab 8.9.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291) in GitLab 8.9.
 
 Award emoji can also be applied to individual comments when you want to
 celebrate an accomplishment or agree with an opinion.
 
-To add an award emoji, click the smile in the top right of the comment and pick
-an emoji from the dropdown. If you want to remove an award emoji, just click
-the emoji again and the vote will be removed.
+To:
+
+- Add an award emoji, click the smile in the top right of the comment and pick an emoji from the dropdown.
+- Remove an award emoji, click the emoji again and the vote will be removed.
 
 ![Picking an emoji for a comment](img/award_emoji_comment_picker.png)
 
 ![An award emoji has been applied to a comment](img/award_emoji_comment_awarded.png)
-
-[2871]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781
-[1825]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825
-[4291]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291
-[ce-9570]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570