Merge branch 'context_help_marianna'
marianna.kononenko
BIN
images/ui/context_help/context_help_alternatives.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/context_help/context_help_alternatives_dark.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/context_help/context_help_explain.png
Normal file
|
After Width: | Height: | Size: 17 KiB |
BIN
images/ui/context_help/context_help_explain_dark.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
BIN
images/ui/context_help/context_help_explain_simple_correct.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
|
After Width: | Height: | Size: 20 KiB |
BIN
images/ui/context_help/context_help_explain_simple_incorrect.png
Normal file
|
After Width: | Height: | Size: 31 KiB |
|
After Width: | Height: | Size: 36 KiB |
BIN
images/ui/context_help/context_help_explain_too_many_correct.png
Normal file
|
After Width: | Height: | Size: 20 KiB |
|
After Width: | Height: | Size: 18 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 21 KiB |
BIN
images/ui/context_help/context_help_explain_ui_correct.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
BIN
images/ui/context_help/context_help_explain_ui_correct_dark.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/context_help/context_help_explain_ui_incorrect.png
Normal file
|
After Width: | Height: | Size: 14 KiB |
|
After Width: | Height: | Size: 13 KiB |
BIN
images/ui/context_help/context_help_inline_text.png
Normal file
|
After Width: | Height: | Size: 35 KiB |
BIN
images/ui/context_help/context_help_inline_text_dark.png
Normal file
|
After Width: | Height: | Size: 34 KiB |
BIN
images/ui/context_help/context_help_input_format.png
Normal file
|
After Width: | Height: | Size: 21 KiB |
BIN
images/ui/context_help/context_help_input_format_dark.png
Normal file
|
After Width: | Height: | Size: 21 KiB |
BIN
images/ui/context_help/context_help_input_warning.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
BIN
images/ui/context_help/context_help_input_warning_dark.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/context_help/context_help_limitation.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
BIN
images/ui/context_help/context_help_limitation_dark.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
BIN
images/ui/context_help/context_help_navigation.png
Normal file
|
After Width: | Height: | Size: 14 KiB |
BIN
images/ui/context_help/context_help_navigation_dark.png
Normal file
|
After Width: | Height: | Size: 14 KiB |
BIN
images/ui/context_help/context_help_terms.png
Normal file
|
After Width: | Height: | Size: 41 KiB |
BIN
images/ui/context_help/context_help_terms_dark.png
Normal file
|
After Width: | Height: | Size: 47 KiB |
BIN
images/ui/context_help/context_help_tooltip.png
Normal file
|
After Width: | Height: | Size: 62 KiB |
BIN
images/ui/context_help/context_help_tooltip_dark.png
Normal file
|
After Width: | Height: | Size: 67 KiB |
BIN
images/ui/context_help/database tool window.png
Normal file
|
After Width: | Height: | Size: 25 KiB |
BIN
images/ui/context_help/database tool window_dark.png
Normal file
|
After Width: | Height: | Size: 24 KiB |
BIN
images/ui/empty_state/empty_state_structure.png
Normal file
|
After Width: | Height: | Size: 72 KiB |
BIN
images/ui/empty_state/empty_state_structure_dark.png
Normal file
|
After Width: | Height: | Size: 33 KiB |
BIN
images/ui/inline_help_text/inline_text_brackets_correct.png
Normal file
|
After Width: | Height: | Size: 9.0 KiB |
BIN
images/ui/inline_help_text/inline_text_brackets_correct_dark.png
Normal file
|
After Width: | Height: | Size: 8.6 KiB |
BIN
images/ui/inline_help_text/inline_text_brackets_incorrect.png
Normal file
|
After Width: | Height: | Size: 8.6 KiB |
|
After Width: | Height: | Size: 8.1 KiB |
BIN
images/ui/inline_help_text/inline_text_external_link.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
BIN
images/ui/inline_help_text/inline_text_external_link_dark.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
BIN
images/ui/inline_help_text/inline_text_formatting_correct.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/inline_help_text/inline_text_formatting_incorrect.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/inline_help_text/inline_text_group.png
Normal file
|
After Width: | Height: | Size: 53 KiB |
BIN
images/ui/inline_help_text/inline_text_group_dark.png
Normal file
|
After Width: | Height: | Size: 50 KiB |
BIN
images/ui/inline_help_text/inline_text_height.png
Normal file
|
After Width: | Height: | Size: 28 KiB |
BIN
images/ui/inline_help_text/inline_text_height_dark.png
Normal file
|
After Width: | Height: | Size: 27 KiB |
BIN
images/ui/inline_help_text/inline_text_internal_link.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
BIN
images/ui/inline_help_text/inline_text_internal_link_dark.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
BIN
images/ui/inline_help_text/inline_text_legal.png
Normal file
|
After Width: | Height: | Size: 57 KiB |
BIN
images/ui/inline_help_text/inline_text_legal_dark.png
Normal file
|
After Width: | Height: | Size: 55 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_bottom.png
Normal file
|
After Width: | Height: | Size: 13 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_bottom_dark.png
Normal file
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 51 KiB |
|
After Width: | Height: | Size: 49 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_bottom_tree.png
Normal file
|
After Width: | Height: | Size: 51 KiB |
|
After Width: | Height: | Size: 49 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_right_button.png
Normal file
|
After Width: | Height: | Size: 9.9 KiB |
|
After Width: | Height: | Size: 9.9 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_right_checkbox.png
Normal file
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 16 KiB |
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_right_tree.png
Normal file
|
After Width: | Height: | Size: 31 KiB |
|
After Width: | Height: | Size: 30 KiB |
BIN
images/ui/inline_help_text/inline_text_repetition_correct.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/inline_help_text/inline_text_repetition_incorrect.png
Normal file
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 13 KiB |
BIN
images/ui/inline_help_text/inline_text_under_table.png
Normal file
|
After Width: | Height: | Size: 25 KiB |
BIN
images/ui/inline_help_text/inline_text_under_table_dark.png
Normal file
|
After Width: | Height: | Size: 25 KiB |
BIN
images/ui/inline_help_text/tooltip_list.png
Normal file
|
After Width: | Height: | Size: 51 KiB |
BIN
images/ui/inline_help_text/tooltip_list_dark.png
Normal file
|
After Width: | Height: | Size: 56 KiB |
@ -4,27 +4,27 @@
|
||||
|
||||
<link-summary>UI guidelines on using inline help texts.</link-summary>
|
||||
|
||||
Inline help text provides useful information about a setting.
|
||||
Inline help texts provide useful information about settings:
|
||||
|
||||
{width=304}
|
||||
<img src="context_help_inline_text.png" width="706" alt="Inline help text"/>
|
||||
|
||||
## When to use
|
||||
<chapter title="When to use" id="when-to-use">
|
||||
<p>Follow the rules for <a href="context_help.md">context help</a>.</p>
|
||||
</chapter>
|
||||
|
||||
Follow the rules for [context help](context_help.md).
|
||||
<chapter title="How to use" id="how_to_use">
|
||||
|
||||
## How to use
|
||||
<chapter title="Text length" id="text_length">
|
||||
Show no more than five lines of help text to not clutter the screen.
|
||||
Text width is limited to 70 characters.
|
||||
|
||||
### Text length and formatting
|
||||
{width=706}
|
||||
|
||||
Show no more than 5 lines of help text not to clutter the screen. Note that the text width is limited to 70 characters.
|
||||
Show more than five lines only when a text cannot be shortened for legal purposes.
|
||||
|
||||
{width=380}
|
||||
{width=706}
|
||||
|
||||
Show more than 5 lines only when a text cannot be shortened for legal purposes.
|
||||
|
||||
{width=396}
|
||||
|
||||
<p>Implementation</p>
|
||||
<chapter title="Implementation" id="implementation_legal" collapsible="true" default-state="collapsed">
|
||||
|
||||
```kotlin
|
||||
panel {
|
||||
@ -46,51 +46,100 @@ panel {
|
||||
}
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
|
||||
Provide a link to the corresponding help article or to a place in the IDE where the related settings can be found.
|
||||
</chapter>
|
||||
<chapter title="Links" id="links">
|
||||
|
||||
Provide a [link](link.md) to the corresponding help article or to a place in the IDE where the related settings can be found.
|
||||
Place the link at the end of the text where possible so that it does not disrupt reading.
|
||||
|
||||
{width=366 style=block}
|
||||
*External link*
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<td width="378">
|
||||
<control>Internal link</control>
|
||||
<img src="inline_text_internal_link.png" alt="Internal link"/>
|
||||
</td>
|
||||
<td width="378">
|
||||
<control>External link</control>
|
||||
<img src="inline_text_external_link.png" alt="External link"/>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</chapter>
|
||||
|
||||
{width=345 style=block}
|
||||
*Local link*
|
||||
<chapter title="Text style formatting" id="text_style_formatting">
|
||||
|
||||
Text style formatting:
|
||||
<chapter title="Avoid highlighting" id="avoid_highlighting">
|
||||
Avoid text highlighting. Usually, the help text is short, and no highlighting in bold or italics is needed:
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<td width="378">
|
||||
<format color="369650" style="bold">Correct</format>
|
||||
<img src="inline_text_formatting_correct.png" alt="Avoid highlighting: correct"/>
|
||||
</td>
|
||||
<td width="378">
|
||||
<format color="E55765" style="bold">Incorrect</format>
|
||||
<img src="inline_text_formatting_incorrect.png" alt="Avoid highlighting: incorrect"/>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</chapter>
|
||||
|
||||
* Avoid text highlighting. Usually, the help text is short and no bold or italics are needed.
|
||||
[//]: # (* Use formatting for code, console commands, or parameters. Use HTML tags. Enclosing text in `<html></html>` tags is not needed.)
|
||||
|
||||
{width=364}
|
||||
[//]: # ( {width=213})
|
||||
|
||||
* Use formatting for code, console commands, or parameters. Use HTML tags. Enclosing text in `<html></html>` tags is not needed.
|
||||
<chapter title="Avoid brackets" id="avoid_brackets">
|
||||
Avoid using brackets in control labels and place this information in the inline text instead:
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<td width="378">
|
||||
<format color="369650" style="bold">Correct</format>
|
||||
<img src="inline_text_brackets_correct.png" alt="Avoid brackets: correct"/>
|
||||
</td>
|
||||
<td width="378">
|
||||
<format color="E55765" style="bold">Incorrect</format>
|
||||
<img src="inline_text_brackets_incorrect.png" alt="Avoid brackets: incorrect"/>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</chapter>
|
||||
</chapter>
|
||||
|
||||
{width=213}
|
||||
<chapter title="Writing guidelines" id="writing_guidelines">
|
||||
|
||||
Avoid using brackets.
|
||||
- Make help text [short and descriptive](writing_short.md).
|
||||
|
||||
{width=362}
|
||||
- Do not repeat the setting name in the help text:
|
||||
|
||||
### Writing guidelines
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<td width="378">
|
||||
<format color="369650" style="bold">Correct</format>
|
||||
<img src="inline_text_repetition_correct.png" alt="Avoid brackets: correct"/>
|
||||
</td>
|
||||
<td width="378">
|
||||
<format color="E55765" style="bold">Incorrect</format>
|
||||
<img src="inline_text_repetition_incorrect.png" alt="Avoid brackets: incorrect"/>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</chapter>
|
||||
</chapter>
|
||||
|
||||
Make help text [short and descriptive](writing_short.md).
|
||||
<chapter title="Placement" id="placement">
|
||||
|
||||
Do not repeat the setting name in the help text.
|
||||
|
||||
{width=481}
|
||||
|
||||
## Placement
|
||||
|
||||
### Labeled input, button, checkbox, or radio button
|
||||
|
||||
Labeled inputs are fields, combo boxes, or text areas.
|
||||
|
||||
Place the help text to the right of a labeled input, checkbox, or radio button if all the following applies:
|
||||
<chapter title="Labeled inputs, checkboxes, radio buttons, and buttons" id="small_ui_controls">
|
||||
|
||||
Place the help text to the right of labeled inputs (fields, combo boxes, or text areas), checkboxes, buttons, or radio buttons if all the following applies:
|
||||
* The space to the right is empty.
|
||||
* The help text has 1–5 words, not counting articles and prepositions.
|
||||
* The control label has 1–5 words.
|
||||
|
||||
{width=433}
|
||||
<tabs>
|
||||
<tab title="Labeled inputs" id="labeled_input_inline_text">
|
||||
<img src="inline_text_on_the_right_input_field.png" width="706" alt="Input fields with inline texts on the right"/>
|
||||
<chapter level="4" title="Implementation" id="labeled_input_inline_text_implementation" collapsible="true" default-state="collapsed">
|
||||
|
||||
```kotlin
|
||||
panel {
|
||||
@ -104,8 +153,14 @@ panel {
|
||||
}
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
</tab>
|
||||
|
||||
{width=438}
|
||||
<tab title="Checkboxes" id="checkboxes">
|
||||
|
||||
<img src="inline_text_on_the_right_checkbox.png" width="706" alt="Checkboxes with inline texts on the right"/>
|
||||
|
||||
<chapter level="4" collapsible="true" default-state="collapsed" title="Implementation">
|
||||
|
||||
```kotlin
|
||||
panel {
|
||||
@ -119,32 +174,43 @@ panel {
|
||||
}
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
</tab>
|
||||
|
||||
{width=309}
|
||||
<tab title="Buttons" id="buttons">
|
||||
<img src="inline_text_on_the_right_button.png" width="706" alt="Button with inline texts on the right"/>
|
||||
</tab>
|
||||
</tabs>
|
||||
|
||||
Otherwise, place the help text under the UI control.
|
||||
In other cases, place the help text under the UI controls:
|
||||
|
||||
{width=484}
|
||||
<img src="inline_text_on_the_bottom.png" width="706" alt="Input filed with inline text on the bottom"/>
|
||||
|
||||
<chapter level="4" title="Implementation" id="implementation_under_input_filed" collapsible="true" default-state="collapsed">
|
||||
|
||||
```kotlin
|
||||
panel {
|
||||
row("Default directory:") {
|
||||
textFieldWithBrowseButton()
|
||||
.comment(
|
||||
"Preselected in \"Open ...\" and \"New | Project\" dialogs"
|
||||
"Preselected in Open and New | Project dialogs"
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
|
||||
If there is no space under the UI control, use the [help tooltip](tooltip.md#question-mark-icon-for-help-tooltips) with the question mark icon for labeled inputs, checkboxes, and radio buttons.
|
||||
For buttons, use the help tooltip without the icon.
|
||||
</chapter>
|
||||
|
||||
### List, tree or table
|
||||
|
||||
<chapter title="Trees, lists, and tables" id="trees_lists_tables">
|
||||
<chapter title="Text applies to the whole component" id="whole_component">
|
||||
If the help text applies to a whole list, tree, or table, place it below the control.
|
||||
|
||||
{width=531}
|
||||
<img src="inline_text_under_table.png" width="706" alt="Inline text under the table"/>
|
||||
|
||||
<chapter title="Implementation" id="implementation_table" collapsible="true" default-state="collapsed">
|
||||
|
||||
```kotlin
|
||||
|
||||
@ -163,31 +229,36 @@ panel {
|
||||
}.resizableRow()
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
</chapter>
|
||||
<chapter title="Text applies to a single item" id="single_item">
|
||||
If the help text applies to a single list, tree, or table item, its location will depend on its length.
|
||||
<chapter title="Short texts" id="short_texts">
|
||||
Place short texts (1–10 words) to the right of the item:
|
||||
|
||||
If it applies to a single list, tree or table item:
|
||||
<img src="inline_text_on_the_right_tree.png" width="706" alt="Inline text under the table"/>
|
||||
</chapter>
|
||||
<chapter title="Long texts" id="long_texts">
|
||||
|
||||
* If the help text has 1–10 words, place it to the right of the item.
|
||||
*
|
||||
* Place longer texts (more than 10 words) into the detail part of master-detail layouts:
|
||||
|
||||
{width=422}
|
||||
<img src="inline_text_on_the_bottom_master_detail.png" width="706" alt="Inline text on the bottom of the master detail layout"/>
|
||||
|
||||
* If the text is longer than 10 words:
|
||||
* For other cases, use the [help tooltip](tooltip.md#question-mark-icon-for-help-tooltips) with the question mark icon:
|
||||
|
||||
<p>For a list or tree in the master part, place the text into the detail part.</p>
|
||||
<img src="tooltip_list.png" width="706" alt="Inline text on the bottom of the master detail layout"/>
|
||||
|
||||
{width=673}
|
||||
</chapter>
|
||||
</chapter>
|
||||
</chapter>
|
||||
|
||||
If the case with the master-detail layout above does not apply, use the [help tooltip](tooltip.md#question-mark-icon-for-help-tooltips) with the question mark icon.
|
||||
|
||||
{width=390}
|
||||
|
||||
### Group of controls
|
||||
<chapter title="Group of controls" id="group_of_controls">
|
||||
|
||||
If the help text applies to several UI controls, place it at the bottom of the group.
|
||||
|
||||
{width=430}
|
||||
<img src="inline_text_group.png" width="706" alt="Inline text for a group of controls"/>
|
||||
|
||||
<p>Implementation</p>
|
||||
<chapter title="Implementation" id="implementation_group" collapsible="true" default-state="collapsed">
|
||||
|
||||
Use [`Panel.group()`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Panel.kt) as the border for panels that need title and possibly the gray line on the right of the title:
|
||||
|
||||
@ -220,4 +291,9 @@ panel {
|
||||
}
|
||||
```
|
||||
|
||||
You can find more examples by invoking the <ui-path>Tools | Internal Actions | UI | Kotlin UI DSL | UI DSL Showcase</ui-path> action (available in [internal mode](enabling_internal.md)) and clicking the <control>View source</control> links on specific pages.
|
||||
You can find more examples by invoking the **Tools | Internal Actions | UI | Kotlin UI DSL | UI DSL Showcase** action (available in [internal mode](enabling_internal.md) and clicking the **View source** links on specific pages.
|
||||
|
||||
</chapter>
|
||||
</chapter>
|
||||
</chapter>
|
||||
|
||||
|
||||
@ -4,101 +4,148 @@
|
||||
|
||||
<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)
|
||||
* as [inline help text](inline_help_text.md)
|
||||
* in an [empty state](empty_state.md)
|
||||
## Inline help text
|
||||
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.
|
||||
|
||||
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
|
||||
## Tooltip
|
||||
|
||||
Use **inline help text** in settings dialogs:
|
||||
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.
|
||||
|
||||
* 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.
|
||||
* Settings dialogs are usually not constrained in space. In most cases, it is possible to fit in a help text.
|
||||
<img src="context_help_tooltip.png" alt="Context help in a tooltip" width="706"/>
|
||||
|
||||
{width=600}
|
||||
|
||||
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.
|
||||
Fill in [empty states](empty_state.md) of tool windows, tables, trees, and other containers with:
|
||||
- a reason why the data is missing
|
||||
- an action that can fix it
|
||||
- a link to a corresponding article in the web help.
|
||||
|
||||
{width=573 style=block}
|
||||
*A refactoring dialog is used more often than a settings dialog. A help tooltip is less distracting than an inline help text.*
|
||||
<img src="empty_state_structure.png" alt="Empty state of a tool window" width="706"/>
|
||||
|
||||
* There is no space for an inline text.
|
||||
|
||||
{width=734}
|
||||
## When to use
|
||||
|
||||
* The control that needs explanation is an icon or does not have a label.
|
||||
|
||||
{width=305}
|
||||
|
||||
## When to use context help
|
||||
|
||||
Explain complex behavior that a short action or a setting name cannot convey clearly.
|
||||
|
||||
{width=543}
|
||||
|
||||
{width=380}
|
||||
|
||||
Explain IDE-specific entities.
|
||||
|
||||
{width=300}
|
||||
|
||||
Provide input format requirements and examples.
|
||||
|
||||
{width=478}
|
||||
|
||||
Suggest alternative ways.
|
||||
|
||||
{width=418}
|
||||
|
||||
Warn about possible problems.
|
||||
|
||||
{width=361}
|
||||
|
||||
Explain limitations.
|
||||
|
||||
{width=432}
|
||||
|
||||
Provide quick navigation to related settings.
|
||||
|
||||
{width=345}
|
||||
|
||||
## 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>
|
||||
|
||||
{width=418}
|
||||
|
||||
Do not explain common actions and entities. Show a regular tooltip with an action name and shortcut in this case.
|
||||
|
||||
<table>
|
||||
Below you will find rules for [tooltips](tooltip.md) and [inline texts](inline_help_text.md).
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<td width="50%"><format color="Red" style="bold">Incorrect</format></td>
|
||||
<td width="50%"><format color="Green" style="bold">Correct</format></td>
|
||||
<td width="378">
|
||||
<img src="context_help_explain.png" alt="Explain a setting"/>
|
||||
</td>
|
||||
<td>
|
||||
<p>Explain complex behavior that a short action or a setting name cannot convey clearly.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><img src="07_explain_obvious_incorrect.png" alt="" width="300" /></td>
|
||||
<td><img src="07_explain_obvious_correct.png" alt="" width="145" /></td>
|
||||
<td width="378">
|
||||
<img src="context_help_input_format.png" alt="Input format requirements"/>
|
||||
</td>
|
||||
<td>
|
||||
<p>Provide input format requirements and examples.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="378">
|
||||
<img src="context_help_alternatives.png" alt="Suggest alternative ways"/>
|
||||
</td>
|
||||
<td>
|
||||
<p>Suggest alternative ways.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="378">
|
||||
<img src="context_help_input_warning.png" alt="Warn about possible issues"/>
|
||||
</td>
|
||||
<td>
|
||||
<p>Warn about possible issues.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="378">
|
||||
<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 explain UI
|
||||
Do not use context help to explain how the user interface works. If you need to explain that, consider redesigning the UI.
|
||||
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<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
|
||||
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">
|
||||
<tr>
|
||||
<td width="378">
|
||||
<format color="369650" style="bold">Correct</format>
|
||||
<img src="context_help_explain_simple_correct.png" alt="Don't explain common actions"/>
|
||||
</td>
|
||||
<td width="378">
|
||||
<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 clutter UI with context help
|
||||
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>
|
||||
|
||||
{width=317}
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<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).
|
||||
|
||||
|
||||