help: Improve emoji and emoticon documentation.

help/configure-emoticon-translations.md

@@ -1,6 +1,6 @@
 # Configure emoticon translations
 
-If you use emoticons like `:)` or `:/`, you can configure whether to have them
+You can configure whether emoticons like `:)` or `:(` will be automatically
 translated into emoji equivalents like
 <img
     src="/static/generated/emoji/images-google-64/1f642.png"
@@ -13,7 +13,7 @@ or
     alt="slight_frown"
     class="emoji-small"
 />
-automatically by Zulip.
+by Zulip.
 
 ## Configure emoticon translations
 
@@ -25,6 +25,12 @@ automatically by Zulip.
 
 {end_tabs}
 
-## Current emoticon translations
+## List of emoticon translations
 
 {emoticon_translations}
+
+## Related articles
+
+* [Emoji and emoticons](/help/emoji-and-emoticons)
+* [Add custom emoji](/help/custom-emoji)
+* [Emoji reactions](/help/emoji-reactions)

help/custom-emoji.md

@@ -42,7 +42,7 @@ emoji. Using REST API endpoints requires some technical expertise;
 You can replace a default emoji by adding a custom emoji of the same
 name. If an emoji has several names, you must use the emoji's primary name
 to replace it. You can find the primary name of an emoji by hovering over it
-in the [emoji picker](/help/emoji-and-emoticons#select-from-the-emoji-picker),
+in the [emoji picker](/help/emoji-and-emoticons#select-an-emoji-from-the-emoji-picker),
 while the search box is empty (you may have to scroll down a bit to find it).
 
 ## Deactivate custom emoji

help/emoji-and-emoticons.md

@@ -1,27 +1,34 @@
 # Emoji and emoticons
 
-## Add emoji to a message
+{!emoji-and-emoticons-intro.md!}
 
-There are several ways to add emoji to a message: typing emoji codes,
+!!! tip ""
-selecting from an emoji picker, using emoticons, or pasting from another
-site.
 
-### Type an emoji code
+    You can also quickly respond to a message by using [emoji reactions](/help/emoji-reactions).
+
+## Use an emoji in your message
+
+### Enter an emoji name
 
 {start_tabs}
 
 {!start-composing.md!}
 
-1. Type `:` followed by a few letters to open the emoji autocomplete. The
+1. Type `:`, followed by a few letters from the emoji name, to see autocomplete
-   letters don't have to be at the beginning of the emoji name; `:ppl` will
+   suggestions. The letters don't have to be at the beginning of the emoji name.
-   match `:apple:`
+   For example, `:app` will match both `:apple:` and `:pineapple:`.
+
+1. Type the full emoji name followed by `:`, or select an emoji from the list of
+   suggestions.
 
 {end_tabs}
 
-If you don't know the code for an emoji, you can see what it's called in the
+!!! tip ""
-emoji picker, or hover over the emoji in a message.
 
-### Select from the emoji picker
+    You can hover over an emoji in the emoji picker, a message, or an [emoji
+    reaction](/help/emoji-reactions) to learn its name.
+
+### Select an emoji from the emoji picker
 
 {start_tabs}
 
@@ -35,9 +42,16 @@ emoji picker, or hover over the emoji in a message.
 
 {end_tabs}
 
-### Use emoticons
+### Use an emoticon
 
-Use `:)` and `:/` instead of typing `:smile:` and `:confused:`.
+You can configure Zulip to convert emoticons into emoji, so that, e.g., `:)`
+will be displayed as
+<img
+    src="/static/generated/emoji/images-google-64/1f642.png"
+    alt="smile"
+    class="emoji-small"
+/>
+.
 
 {start_tabs}
 
@@ -50,10 +64,14 @@ Use `:)` and `:/` instead of typing `:smile:` and `:confused:`.
 The list of supported emoticons is available
 [here](/help/configure-emoticon-translations).
 
-### Paste from another site
+### Paste an emoji
 
-Copying and pasting emoji from other sites generally works.
+You can paste an emoji copied from outside of Zulip directly into the compose
-[Contact us](/help/contact-support) if you find a site where it doesn't!
+box.
+
+## Examples
+
+{!emoji-and-emoticons-examples.md!}
 
 ## Change your emoji set
 
@@ -80,3 +98,4 @@ you send. Zulip emoji are compatible with screen readers and other accessibility
 
 * [Add custom emoji](/help/custom-emoji)
 * [Emoji reactions](/help/emoji-reactions)
+* [Configure emoticon translations](/help/configure-emoticon-translations)

help/format-your-message-using-markdown.md

@@ -82,15 +82,9 @@ whenever you need a reminder of the formatting syntax below.
 
 ## Emoji and emoticons
 
-To translate emoticons into emoji, you'll need to
+{!emoji-and-emoticons-intro.md!}
-[enable emoticon translations](/help/configure-emoticon-translations).
-You can also [add custom emoji](/help/custom-emoji).
 
-```
+{!emoji-and-emoticons-examples.md!}
-:octopus: :heart: :zulip: :)
-```
-
-![Markdown emoji](/static/images/help/markdown-emoji.png)
 
 ## Mentions
 

help/include/emoji-and-emoticons-examples.md

@@ -0,0 +1,9 @@
+### What you type
+
+```
+:octopus: :heart: :zulip: :)
+```
+
+### What it looks like
+
+![Markdown emoji](/static/images/help/markdown-emoji.png)

help/include/emoji-and-emoticons-intro.md

@@ -0,0 +1,15 @@
+There are several ways to use an emoji in your message:
+
+- [Enter an emoji name](/help/emoji-and-emoticons#enter-an-emoji-name)
+  surrounded by `:`, with help from autocomplete suggestions.
+
+- [Select an emoji from the emoji
+  picker](/help/emoji-and-emoticons#select-an-emoji-from-the-emoji-picker)
+
+- [Use an emoticon](/help/emoji-and-emoticons#use-an-emoticon)
+
+- [Paste an emoji](/help/emoji-and-emoticons#paste-an-emoji)
+
+You can [add custom emoji](/help/custom-emoji) for your organization. Like
+default emoji, custom emoji can be entered into the compose box by name, or
+selected from the emoji picker.