UX-2323 Update existing UI Guidelines: Context help

topics/ui/principles/context_help.md

@@ -4,101 +4,143 @@
 
 <link-summary>Choosing a proper component for context help.</link-summary>
 
-Use context help to briefly explain how a functionality works if it is not clear from the UI and the application behavior. Provide a full description of the functionality in [product web help](https://www.jetbrains.com/help/idea/).
+Use context help to briefly explain how a functionality works if it is not clear from the UI or the application behavior. A full description of the functionality should be provided in [product web help](https://www.jetbrains.com/help/idea/).
 
-There are three ways to show context help:
+Context help can be shown as an [inline help text](inline_help_text.md), in a [help tooltip](tooltip.md), and in an [empty state](empty_state.md).
 
-* in a [help tooltip](tooltip.md)
+## Inline help text
-* as [inline help text](inline_help_text.md)
-* in an [empty state](empty_state.md)
 
-This article explains when to use the first two. For when to use the empty state, see the [](empty_state.md) topic.
+<img src="context_help_inline_text.png" alt="Context help in an inline text" width="706"/>
 
-## Inline text or a tooltip
+Use an [inline help text](inline_help_text.md) in settings dialogs that are not constrained by space and are not frequently used. Since settings are rarely changed, users may forget their purpose, so displaying the information immediately makes sense.
 
-Use **inline help text** in settings dialogs:
+## Tooltip
 
-* Settings are rarely changed. Users may forget what a setting does when they use it the next time, so it makes sense to provide additional information straight away.
+<img src="context_help_tooltip.png" alt="Context help in a tooltip" width="706"/>
-* Settings dialogs are usually not constrained in space. In most cases, it is possible to fit in a help text.
 
-![](09_use_inline_help_text.png){width=600}
+Use a [tooltip](tooltip.md):
+- If the space is not enough for showing the inline help text.
+- In frequently used dialogs, tool windows, or popups. The more often a person uses an interface, the more likely they are to remember what each option does.
+- For icons or other controls that do not have a label.
 
-Use a **help tooltip** if:
+## Empty state
 
-* A dialog is often used. The more often a person uses an interface, the more likely they are to remember what each option does.
+<img src="empty_state_structure.png" alt="Empty state of a tool window" width="706"/>
 
-  ![](10_use_help_tooltip.png){width=573 style=block}
+Fill in [empty states](empty_state.md) of tool windows, tables, trees, and other containers with:
-  *A refactoring dialog is used more often than a settings dialog. A help tooltip is less distracting than an inline help text.*
+- a reason why the data is missing
+- an action that can fix it
+- a link to a corresponding article in the web help.
 
-* There is no space for an inline text.
+## When to use
 
-  ![](11_no_space_in_settings.png){width=734}
+Below you will find rules for [tooltips](tooltip.md) and [inline texts](inline_help_text.md).
-
+<table style="none" border="false" column-width="fixed">
-* The control that needs explanation is an icon or does not have a label.
+  <tr>
-
+    <td width="378">
-  ![](03_action_help_tooltip.png){width=305}
+      <img src="context_help_explain.png" alt="Explain a setting"/>
-
+    </td>
-## When to use context help
+    <td>
-
+        <p>Explain complex behavior that a short action or a setting name cannot convey clearly.</p>
-Explain complex behavior that a short action or a setting name cannot convey clearly.
+    </td>
-
+  </tr>
-![](04_question_icon_tooltip.png){width=543}
+  <tr>
-
+    <td width="378">
-![](02_text_size.png){width=380}
+      <img src="context_help_input_format.png" alt="Input format requirements"/>
-
+    </td>
-Explain IDE-specific entities.
+    <td>
-
+        <p>Provide input format requirements and examples.</p>
-![](01_IDE_specific.png){width=300}
+    </td>
-
+  </tr>
-Provide input format requirements and examples.
+  <tr>
-
+    <td width="378">
-![](02_formatting_example.png){width=478}
+      <img src="context_help_alternatives.png" alt="Suggest alternative ways"/>
-
+    </td>
-Suggest alternative ways.
+    <td>
-
+        <p>Suggest alternative ways.</p>
-![](03_alternative_ways.png){width=418}
+    </td>
-
+  </tr>
-Warn about possible problems.
+  <tr>
-
+    <td width="378">
-![](04_possible_problems.png){width=361}
+      <img src="context_help_input_warning.png" alt="Warn about possible issues"/>
-
+    </td>
-Explain limitations.
+    <td>
-
+        <p>Warn about possible issues.</p>
-![](05_limitations.png){width=432}
+    </td>
-
+  </tr>
-Provide quick navigation to related settings.
+  <tr>
-
+    <td width="378">
-![](04_link_internal.png){width=345}
+      <img src="context_help_limitation.png" alt="Explain limitations"/>
+    </td>
+    <td>
+        <p>Explain limitations.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="378">
+      <img src="context_help_navigation.png" alt="Provide quick navigation to related settings"/>
+    </td>
+    <td>
+        <p>Provide quick navigation to related settings.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="378">
+      <img src="context_help_terms.png" alt="Explain IDE-specific entities"/>
+    </td>
+    <td>
+        <p>Explain IDE-specific entities.</p>
+    </td>
+  </tr>
+</table>
 
 ## When not to use
 
 Do not use context help to explain how the user interface works. If you need to explain that, consider redesigning the UI.
 
-<format color="Red" style="bold">Incorrect</format>
+<table style="none" border="false" column-width="fixed">
-
+  <tr>
-![](06_explain_how_ui_works.png){width=418}
+    <td width="378">
+      <format color="369650" style="bold">Correct</format>
+      <img src="context_help_explain_ui_correct.png" alt="Don't explain how UI elements should work"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="context_help_explain_ui_incorrect.png" alt="Incorrect UI requires additional explanation"/>
+    </td>
+  </tr>
+</table>
 
 Do not explain common actions and entities. Show a regular tooltip with an action name and shortcut in this case.
-
+<table style="none" border="false" column-width="fixed">
-<table>
   <tr>
-    <td width="50%"><format color="Red" style="bold">Incorrect</format></td>
+    <td width="378">
-    <td width="50%"><format color="Green" style="bold">Correct</format></td>
+      <format color="369650" style="bold">Correct</format>
-  </tr>
+      <img src="context_help_explain_simple_correct.png" alt="Don't explain common actions"/>
-  <tr>
+    </td>
-    <td><img src="07_explain_obvious_incorrect.png" alt="" width="300" /></td>
+    <td width="378">
-    <td><img src="07_explain_obvious_correct.png" alt="" width="145" /></td>
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="context_help_explain_simple_incorrect.png" alt="Common actions are explained in the tooltip"/>
+    </td>
   </tr>
 </table>
 
 Do not explain each option. Too many help icons or too much inline text make a dialog cluttered and harder to navigate visually.
 If all options need to be explained, consider rewriting the labels to make them clearer.
 
-<format color="Red" style="bold">Incorrect</format>
+<table style="none" border="false" column-width="fixed">
-
+  <tr>
-![](08_explain_all_options.png){width=317}
+    <td width="378">
-
+      <format color="369650" style="bold">Correct</format>
+      <img src="context_help_explain_too_many_correct.png" alt="Don't explain every option"/>
+    </td>
+    <td width="378">
+      <format color="E55765" style="bold">Incorrect</format>
+      <img src="context_help_explain_too_many_incorrect.png" alt="Every option has its tooltip"/>
+    </td>
+  </tr>
+</table>
 ## How to use
 
-See [Inline help text](inline_help_text.md) and [Tooltip](tooltip.md).
+See [Inline help text](inline_help_text.md), [Tooltip](tooltip.md), and [](empty_state.md).