hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-28 01:07:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

Updated How to Write Guidelines

Browse Source
This commit is contained in:
marianna.kononenko 2024-10-16 13:01:09 +02:00
parent 26174750f8
commit b3c7cb494c
7 changed files with 439 additions and 321 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
ijs.tree
View File

@ -547,7 +547,7 @@
<toc-element toc-title="Resources"> <toc-element toc-title="Resources">
<toc-element href="https://intellij-icons.jetbrains.design" toc-title="Icons List"/> <toc-element href="https://intellij-icons.jetbrains.design" toc-title="Icons List"/>
<toc-element topic="icons_list.md" hidden="true"/> <toc-element topic="icons_list.md" hidden="true"/>
<toc-element topic="how_to_write_guidelines.md"/> <toc-element topic="how_to_write_guidelines.topic"/>
<toc-element topic="UI_kit.md"/> <toc-element topic="UI_kit.md"/>
</toc-element> </toc-element>
</toc-element> </toc-element>

BIN
images/ui/how_to_write_guidelines/Callouts.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
images/ui/how_to_write_guidelines/Callouts_dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

4
topics/ui/controls/built_in_button.md
View File

@ -26,9 +26,9 @@ The shortcut for a built-in button is <shortcut>Shift+Enter</shortcut>.
A browse button opens a dialog with the disk, a tree view or a table of values. A browse button opens a dialog with the disk, a tree view or a table of values.
Use a control with the browse icon for a file/folder path selected from the disk. Use a control with the browse icon for a file/folder path selected from the disk.
![](input_browse.png){width=250} ![](input_browse.png){width=378}
An input field with browse button: [`TextFieldWithBrowseButton`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/TextFieldWithBrowseButton.java) [//]: # (An input field with browse button: [`TextFieldWithBrowseButton`]&#40;%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/TextFieldWithBrowseButton.java&#41;)
A combo box with browse button: A combo box with browse button:
<tabs group="languages"> <tabs group="languages">

21
topics/ui/controls/button.topic
View File

@ -17,7 +17,6 @@
</p> </p>
</tldr> </tldr>
<img src="button_example.png" alt="Cancel and Save buttons" width="706"/> <img src="button_example.png" alt="Cancel and Save buttons" width="706"/>
<chapter title="When to use" id="when-to-use"> <chapter title="When to use" id="when-to-use">
<p>Use a button to invoke an immediate action:</p> <p>Use a button to invoke an immediate action:</p>
@ -31,7 +30,7 @@
<list> <list>
<li><p>The action takes the user to another page of the same dialog or an external source like <li><p>The action takes the user to another page of the same dialog or an external source like
documentation.</p> documentation.</p>
<tip>Exception: the <control>Next</control> and <control>Previous</control> buttons in wizard navigation.</tip> <note>Exception: the <control>Next</control> and <control>Previous</control> buttons in wizard navigation.</note>
</li> </li>
<li> <li>
The command is a secondary action that isn't related to the primary purpose of the window, The command is a secondary action that isn't related to the primary purpose of the window,
@ -74,10 +73,10 @@
</chapter> </chapter>
<chapter title="Use imperative verbs" id="use-imperative-verbs"> <chapter title="Use imperative verbs" id="use-imperative-verbs">
<p>Write the label as an imperative verb, for example, Save, Print, Cancel. Use title capitalization.</p> <p>Write the label as an imperative verb, for example, Save, Print, Cancel. Use title capitalization.</p>
<tip><p>Exceptions: standard buttons like <control>OK</control>, <control>Back</control>/<control>Forward</control>, <note><p>Exceptions: standard buttons like <control>OK</control>, <control>Back</control>/<control>Forward</control>,
<control>Previous</control>/<control>Next</control>, <control>Yes</control>/<control>No</control>, <control>Agree</control>, <control>Previous</control>/<control>Next</control>, <control>Yes</control>/<control>No</control>, <control>Agree</control>,
<control>Options</control>, <control>Settings</control>, <control>Details</control>. <control>Options</control>, <control>Settings</control>, <control>Details</control>.
</p></tip> </p></note>
</chapter> </chapter>
<chapter title="Be specific" id="be-specific"> <chapter title="Be specific" id="be-specific">
<p>The button should answer the question in the title, so the user can skip the description. Prefer specific <p>The button should answer the question in the title, so the user can skip the description. Prefer specific
@ -101,11 +100,11 @@
<td><img src="default_OK.png" alt="An incorrect button with a generic 'OK' label" width="378"/></td> <td><img src="default_OK.png" alt="An incorrect button with a generic 'OK' label" width="378"/></td>
</tr> </tr>
</table> </table>
<tip> <note>
Exception: the <control>Cancel</control> button if it's clear what action is being canceled. Exception: the <control>Cancel</control> button if it's clear what action is being canceled.
For example, use For example, use
<control>Cancel</control> instead of <control>Don’t Create</control>. <control>Cancel</control> instead of <control>Don’t Create</control>.
</tip> </note>
<p>Do not <p>Do not
use the word use the word
<control>Now</control> in labels because buttons always trigger an immediate action: <control>Now</control> in labels because buttons always trigger an immediate action:
@ -125,9 +124,9 @@
</tr> </tr>
<tr> <tr>
<td> <td>
<img src="check_for_updates.png" alt="A button with 'Check for Updates' label" width="384"/> <img src="check_for_updates.png" alt="A button with 'Check for Updates' label" width="378"/>
</td> </td>
<td><img src="check_now_button.png" alt="A button with 'Check Now' label" width="336"/></td> <td><img src="check_now_button.png" alt="A button with 'Check Now' label" width="378"/></td>
</tr> </tr>
</table> </table>
</chapter> </chapter>
@ -153,7 +152,7 @@
<td><img src="active_edit_action.png" <td><img src="active_edit_action.png"
alt="A button with the 'Edit Action Icon...' label" alt="A button with the 'Edit Action Icon...' label"
width="378"/></td> width="378"/></td>
<td><img src="active_edit.png" alt="A button with 'Edit...' label" width="378"/></td> <td><img src="active_edit.png" alt="A button with 'Edit' label" width="378"/></td>
</tr> </tr>
</table> </table>
</chapter> </chapter>
@ -188,13 +187,13 @@
or or
<shortcut>Cmd+Enter</shortcut> <shortcut>Cmd+Enter</shortcut>
on macOS. on macOS.
<tip>Exception: if the focus is on an element that uses the <note>Exception: if the focus is on an element that uses the
<shortcut>Enter</shortcut> <shortcut>Enter</shortcut>
key, for example, a text area, the default button is triggered only by key, for example, a text area, the default button is triggered only by
<shortcut>Ctrl+Enter</shortcut> <shortcut>Ctrl+Enter</shortcut>
on Windows/Linux and on Windows/Linux and
<shortcut>Cmd+Enter</shortcut> <shortcut>Cmd+Enter</shortcut>
on macOS.</tip> on macOS.</note>
</li> </li>
<li>The default button should always be present in a dialog. Only one button in a dialog can be the default <li>The default button should always be present in a dialog. Only one button in a dialog can be the default
one. one.

307
topics/ui/resources/how_to_write_guidelines.md
View File

@ -1,307 +0,0 @@
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# How to Write Guidelines
<link-summary>Workflow and basic rules of writing articles for IntelliJ Platform UI Guidelines.</link-summary>
<p>This page describes the basic rules of writing articles for IntelliJ Platform UI Guidelines.</p>
[//]: # (## Workflow)
[//]: # ()
[//]: # (Follow these steps if you want to add a new article to the guidelines:)
[//]: # (1. Write an article in the Google doc.)
[//]: # (2. Share the Google doc with the designers team, so they can review and comment the document.)
[//]: # (3. When all comments are resolved, send the Google doc to tech writers for grammar review. [Create ticket]&#40;https://youtrack.jetbrains.com/newIssue?project=DOC&clearDraft=true&c=Type+Task&c=Assignee+Anna.Gasparyan&c=Subsystem+IntelliJ+IDEA&#41; in YouTrack project “Documentation”, subsystem “IntelliJ IDEA”, auto-assigned to Anna Gasparyan.)
[//]: # (4. After the review, add the article to the guidelines. Follow the instructions on [https://github.com/JetBrains/ui]&#40;https://github.com/JetBrains/ui&#41;.)
[//]: # (4. Contact developers to add Code Snippets to the article.)
## Text
The text should be short and clear. Follow the rules:
### Grammar
<table style="none">
<tr>
<td> Use present tense.</td>
<td style="font-style:italic"> A progress bar <font color="#18B04B">informs </font> user about the progress of a lengthy operation. </td>
</tr>
<tr>
<td> Write in the active voice. </td>
<td style="font-style:italic"> Progress bar <font color="#FF001B">is shown</font>.<br /> Progress bar <font color="#18B04B">appears</font>. </td>
</tr>
<tr>
<td> Avoid unnecessary modal verbs. </td>
<td style="font-style:italic"> Label <font color="#FF001B">should use</font> sentence-style capitalization.<br /> <font color="#18B04B">Use</font> sentence capitalization in labels. </td>
</tr>
<tr>
<td> Use imperatives. </td>
<td style="font-style:italic"><font color="#FF001B">The cursor changes</font> to the pointing hand.<br /> <font color="#18B04B">Change the cursor</font> to the pointing hand. </td>
</tr>
<tr>
<td> Do not address the reader. </td>
<td style="font-style:italic"> Use combobox if..., Follow guidelines... </td>
</tr>
<tr>
<td> When describing user behavior, write: </td>
<td style="font-style:italic"> A <font color="#18B04B"> user looks </font> forward to what will appear after completion. </td>
</tr>
<tr>
<td> Avoid bracketed text, it complicates reading. If information is important — put it in a new sentence, if not — remove it. </td>
<td style="font-style:italic">Provide a header <font color="#FF001B">(bold)</font> for each progress. <br /> Provide a <font color="#18B04B">bold</font> header for each progress. </td>
</tr>
</table>
### Contents
* Omit common introductory phrases.
* Write one idea per sentence.
* Split the text to subsections and short paragraphs.
* Use bulleted lists when the order of points does not matter, and numbered list when they do.
* When giving a recommendation, explain why it is useful.
*Bad: *If a process is started by a user, provide a notification when the process finishes*.
* Good>: *If a process is started by a user, provide a notification when the process finishes. This way the user, if switched to another task while waiting for a process to finish, would know they can return back and see the results*.
* Add links if you refer to other sections. Links should be descriptive, do not use *Click here* links.
### Word-level recommendations
<table style="none">
<tr>
<td> <i>Would be</i> — use <i>is</i> instead, when possible. </td>
<td> Displaying indicator <font color="#FF001B">would be</font> distracting.<br />Displaying indicator <font color="#18B04B">is</font> distracting. </td>
</tr>
<tr>
<td> <i>Then</i> — omit if possible. </td>
<td> If a process is started by the user, <font color="#FF001B">then</font>. provide notification.</td>
</tr>
<tr>
<td> <emphasis>He/she</emphasis> — replace with <emphasis>they</emphasis>. </td>
<td> If a process lasts less than 1 second, the user won’t be able to read the process name and showing it would just distract <font color="#18B04B">them</font>.</td>
</tr>
<tr>
<td> Select a word with <b>bold</b> to emphasise or with <i>italic</i> to quote. </td>
</tr>
</table>
## Structure
If an article is about a control, add a control's class name under the article title:
<code-block lang="java">
codename: JButton
</code-block>
Structure a single guideline as follows:
* Start each guideline with a text description and provide an image *under* it if necessary. Do **not** use a reversed order (image than text).
* Place an additional text under the image only if it does not make sense placing it with the text above the image.
Guideline numbered anchors:
* Each paragraph `<p>` is assigned a numbered anchor. An anchor helps referencing a particular guideline. Structure the article so that each guideline is a single paragraph.
* To start a new paragraph, add an empty line above.
* To create a text block without an anchor, do not add an empty line above. Add two spaces in the end of the previous text block.
* To add extra vertical space without creating a paragraph, use `<br/>`.
* If some element gets an unnecessary anchor, use the class `noanchor`. Note that Markdown does not work inside the `<p>` tag, replace it with HTML. Example:
<code-block>{% highlight html %}</code-block>
<p>
For when to use the empty state, see the
<a href="empty_state.md">Empty State</a>.
</p>
The article structure can vary depending on whether a control, component or principle is described. Generally, use the sections that are described below.
### Introduction paragraph
In the first paragraph describe a control, component or principle and provide an illustration. If there are different types of the control, describe all of them.
### When to use
Describe when to use the control or when to apply the principle.
If the control is often used incorrectly, describe cases when the control should not be used.
### How to use
Provide guidelines on how to use the control, component or principle. Group guidelines by their subject. For a control it can be:
* Behavior details for a single control and for a group of such controls (if applicable)
* Wording — how to write a label for the control
* Using the control with other controls
* Any other recommendations specific to this control
Use notes for links to additional materials, sources, useful facts and examples. To insert a note, use:
<code-block>{% highlight html %}&lt;note>Note text&lt;/note></code-block>
Use formatting for <shortcut>shortcuts</shortcut>:
<code-block>{% highlight html %}&lt;shortcut>Ctrl+Space&lt;/shortcut></code-block>
To add a horizontal line in a table, use:
<code-block>{% highlight html %}</code-block>
### Sizes and placement
Give recommendations for:
* Minimum and maximum sizes in pixels
* How to layout with other controls. Refer to [Layout](layout.md) if possible.
* Insets between controls in pixels
Illustrate sizes and insets as [described below](#colors-insets-and-sizes).
### Style
Provide [an illustration](#style) how a control or component looks in different look-and-feels.
List color keys used for this control.
Do not provide font properties and specific hex colors.
## Images
Illustrate all statements with interface examples. Use **default macOS** theme as the main themes for illustrations. Add a section with examples for Darcula theme in the Google doc, but do not move it to the official guidelines.
If an image description appears above the image, end it with a colon:
![](example_1.png){width=312}
If under, do not use a period at the end:
![](example_1.png){width=312}
*Image description*
Several not wide images can be placed in two or three columns:
![](example_2.png){width=760}
If there is a set of images that illustrates the sequence of states, place them horizontally or vertically and link with an arrow:
![](example_3.png){width=565}
If there is a common mistake in UI, provide Correct/Incorrect images:
![](corret_incorrect.png){width=417}
The “Correct/Incorrect” can be placed above the image or on the left:
![](correct_incorrect_vertical.png){width=285}
If there is one image and it’s not big, cross out the image with 1px line instead of “Incorrect” header:
![](incorrect.png){width=268}
Use html to add Correct/Incorrect label:
<code-block>{% highlight html %}&lt;p>Incorrect&lt;/p>
</code-block>
![](correct_incorrect_sizes.png){width=530}
Save all images in two sizes: example.png and example@2x.png.
### Callouts
All text on images should be horizontally oriented.
Font-style: Gotham Book
Font-size: 14px
Line height: 20px
Max width: 300px
Color: #999999
Place callouts around the image at a distance of at least 30px:
![](callout_1.png){width=474}
Or use leader lines to sign specific items on the image:
![](callout_2.png){width=330}
**Leader line** is 1px line, color: #000000 op. 0.3.
Line is vertical or horizontal. It can be bent once if there is not enough space for the text. Do not intersect lines.
Leave 1px between the line and the element to which it refers or place line over the element:
![](leader_lines_1.png){width=182}
Lines go beyond the image by 20px:
![](leader_lines_2.png){width=353}
Text position:
![](leader_lines_3.png){width=452}
If line is horizontal, center it with the first comment line.
### Colors, insets and sizes
Use the Hex Code format to specify colors:
![](how_to_write_guidelines_colors.png){width=252}
Use colored rectangles to specify sizes inside the element and lines to specify external sizes:
![](insets.png){width=377}
* Main rectangle: <span style="color:#DA769D">#DA769D</span> op. 0.4.
* Secondary rectangle: <span style="color:#6D9AE6">#6D9AE6</span> op. 0.4.
* Text and line: <span style="color:#BD136B">#BD136B</span>, <span style="color:#0054C0">#0054C0</span>.
* Distance between image and line, between line and text is 5px.
* Align all sizes on the right.
Use line to show that text is aligned with an element:
![](how_to_write_guidelines_alignment.png){width=155}
Specify the element sizes in the following format:
![](how_to_write_guidelines_sizes.png){width=54}
For text labels, specify insets from the bounding box:
![](boundingBox.png){width=216}
![](insetsText.png){width=125}
Parameters for regular labels that make bounding boxes in Sketch the same size as in Java (already used in Sketch libraries symbols):
- *macOS*: SF UI Text Medium / 13 size / –0.1 character spacing / 16 line spacing
- *Windows*: Segoe UI Regular / 12 size / 16 line spacing
- *Linux*: Ubuntu Regular / 15 size / 18 line spacing
If unsure about a bounding box size for other font sizes, check with UI Inspector.
<!--
If there are many properties for different themes, put them in the table:
![](tdemes.png)
-->
## Code snippets
Provide code snippets along the article to help developers implement the described look and behavior.
If a code snippet is too big, put it at the end of the article and provide a link.
To insert a snippet, use:
<code-block>
{% highlight html %}{{ "{% highlight java " }}%}
Code snippet
{{ "{% endhighlight " }}%}
</code-block>

426
topics/ui/resources/how_to_write_guidelines.topic Normal file
View File

@ -0,0 +1,426 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
id="how_to_write_guidelines" title="How to Write Guidelines">
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<title>
How to Write Guidelines
</title>
<link-summary>Basic rules of writing articles for IntelliJ Platform UI Guidelines.</link-summary>
<p>This page describes basic rules of writing articles for IntelliJ Platform UI Guidelines.</p>
<tip>If you want to add new articles or edit existing ones, learn more about the contribution process in <a
href="intellij-sdk-docs-original_CONTRIBUTING.md"/>.
</tip>
<chapter title="Article structure" id="article-structure">
<p>The article structure can vary depending on whether a <a href="Components.topic">component</a> or a <a
href="Principles.md">principle</a> is described.
Most of the articles should include the structural elements listed below.</p>
<chapter title="Useful links" id="useful-links">
<tldr>
<p>
<control>Implementation</control>
:
<a href="https://docs.oracle.com/javase/tutorial/uiswing/components/button.html">JButton</a>
</p>
<p>
<control>Specification</control>
: <a href="https://www.figma.com/design/w8GWsQsHF3XdjdcN1E3X3n/Int-UI-Kit?node-id=733-46953">Button</a>
</p>
</tldr>
Add a block with useful links at the beginning of each article. If an article is about a component, add links to
the component implementation and design specification in the
<code>&lt;tldr&gt;&lt;/tldr&gt;</code> element.
You can add other useful links to this block if needed.
</chapter>
<chapter title="Introduction paragraph" id="introduction-paragraph">
<p>In the first paragraph, describe a component or a principle and provide an <a
anchor="images">illustration</a>.
</p>
</chapter>
<chapter title="Anatomy" id="anatomy">
<p>Add this section if a component consists of several controls.
Provide an image that shows all parts of the component.
Use <a anchor="callouts">callouts</a> to label the component parts:</p>
<img src="Callouts.png" alt="Callouts" width="706"/>
If needed, describe all the parts in details below the image.
</chapter>
<chapter title="When to use" id="when-to-use">
<p>Describe common use cases for the component and provide an <a anchor="images">image</a> for each use case.</p>
</chapter>
<chapter title="When not to use" id="when-not-to-use">
<p>If the component is often misused, describe these cases.
If possible, write which components should be used
instead and provide <a anchor="images">images</a>.</p>
</chapter>
<chapter title="How to use" id="how-to-use">
<p>Provide guidelines on how to use a component, for example:</p>
<list>
<li>Behavior details for a single component and for a group of such components if applicable.</li>
<li>Rules for writing labels, hints, empty state texts.</li>
<li>How to use this component with other components.</li>
<li>Any other recommendations specific to this component.</li>
</list>
<chapter title="Each rule in a separate chapter" id="each-rule-in-a-separate-chapter">
<p>Try to put each rule or a group of rules into a separate subchapter and add a short and descriptive title.
This will allow the reader to scan the information on the page faster and copy the link to the rule if needed.</p>
</chapter>
</chapter>
<chapter title="Sizes, placement, and style details (obsolete)" id="sizes-placement-and-style-details">
<p>Do not describe the component appearance in a separate section. All the details are provided in the <a
href="https://www.figma.com/design/w8GWsQsHF3XdjdcN1E3X3n/Int-UI-Kit?node-id=6222-73687">Int UI Kit</a>
library in Figma.
Make sure that an actual link to Figma is added in the <a anchor="useful-links">useful links</a>.
</p>
</chapter>
</chapter>
<chapter title="Images" id="images">
<procedure title="Create an image" id="create-an-image">
<step><p><a href="https://www.figma.com/design/w8GWsQsHF3XdjdcN1E3X3n/Int-UI-Kit?node-id=8151-76094&amp;t=S6z3MDdUdRxDSUuj-4">Get
the Int UI kit</a> and enable it in Figma.</p>
</step>
<step>
Open the <a
href="https://www.figma.com/design/PTDx2xYquL3GKommsG7cHn/Images?node-id=38-1284&amp;t=MdzqZgCYyGwdej3L-1">Images
Figma file</a> and copy the
<control>Image background</control>
and
<control>Callout</control>
components to your Figma file.
</step>
<step>Create an image by adding Int UI components to the image background. Create the
same image for the Dark theme.
</step>
<step>Export all images into the corresponding folder of the documentation project (../images/ui/&lt;component
name&gt;) in PNG format and x2 scale. For images in Dark theme, add the <code>_dark</code> postfix
to the filename.
</step>
</procedure>
<chapter title="Background" id="background">
<p>Use a gray rounded background for all images. Find details in the <a
href="https://www.figma.com/design/PTDx2xYquL3GKommsG7cHn/Images?node-id=38-1284&amp;t=MdzqZgCYyGwdej3L-1">Figma
file</a>.</p>
</chapter>
<chapter title="Width" id="width">
<p>All images must be either 706 px or 378 px wide.</p>
<chapter title="706 px" id="706-px">
<p>Use 706 px width for images with wide content or for single images that are surrounded by text:</p>
<img src="button_example.png" alt="Cancel and Save buttons" width="706"/>
<p>If an image description appears above the image, end it with a colon.</p>
</chapter>
<chapter title="378 px" id="378-px">
<p>Use 378 px width for images in borderless tables. Use the <code>border="false"</code> attribute for
creating borderless tables.</p>
<p>Put images into borderless tables when listing a set of smaller images with descriptions on the right
or when adding correct/incorrect/acceptable examples.</p>
<p>Sets of smaller images:</p>
<table style="none" border="false">
<tr>
<td width="378"><img src="split_button.png" alt="Using split buttons instead of buttons"
width="378"/></td>
<td>Use a <a href="split_button.md">split button</a> instead if there are more than two related
actions.
</td>
</tr>
<tr>
<td width="378">
<img src="built-in_button.png" alt="Using built-in buttons instead of buttons" width="378"/>
</td>
<td>Use a built-in button instead if it's related to an input field, combo box,
search field.
</td>
</tr>
</table>
<p>Correct/incorrect/acceptable examples:</p>
<table style="none" border="false">
<tr>
<td>
<p>
<format color="369650" style="bold">Correct</format>
</p>
</td>
<td>
<p>
<format color="E55765" style="bold">Incorrect</format>
</p>
</td>
</tr>
<tr>
<td><img src="default_button_save.png" alt="A correct button with a clear 'Save' label"
width="378"/></td>
<td><img src="default_OK.png" alt="An incorrect button with a generic 'OK' label" width="378"/>
</td>
</tr>
</table>
<table style="none" border="false">
<tr>
<td>
<p>
<format color="369650" style="bold">Correct</format>
</p>
</td>
<td>
<p>
<format color="DarkOrange" style="bold">Acceptable</format>
</p>
</td>
</tr>
<tr>
<td><img src="active_edit_action.png"
alt="A button with the 'Edit Action Icon...' label"
width="378"/></td>
<td><img src="active_edit.png" alt="A button with 'Edit' label" width="378"/></td>
</tr>
</table>
</chapter>
</chapter>
<chapter title="Callouts" id="callouts">
<p>Add callouts to describe the <a anchor="anatomy">anatomy</a> of complex components.</p>
<p>All texts on images should be horizontally oriented. Refer to the <a
href="https://www.figma.com/design/PTDx2xYquL3GKommsG7cHn/Images?node-id=38-1284&amp;t=MdzqZgCYyGwdej3L-1)">Figma
file</a> for details.
</p>
<img src="Callouts.png" alt="Callouts example" width="706"/>
</chapter>
</chapter>
<chapter title="Text" id="text">
<p>The guidelines should be short, clear, and consistent. Find the common rules below.</p>
<chapter title="Grammar" id="grammar">
<table style="none">
<tr>
<td width="50%"> Prefer present tense.</td>
<td> A progress bar
<format color="369650">informs</format>
a user about the progress of a lengthy operation.
</td>
</tr>
<tr>
<td> Prefer the active voice.</td>
<td> Progress bar
<format color="E55765">is shown</format>
.<br/> Progress bar <format color="369650">appears</format>.
</td>
</tr>
<tr>
<td> Avoid unnecessary modal verbs.</td>
<td> Label
<format color="E55765">should use</format>
sentence-style capitalization.<br/>
<format color="369650">Use</format>
sentence capitalization in labels.
</td>
</tr>
<tr>
<td> Use imperatives.</td>
<td>
<format color="E55765">The cursor changes</format>
to the pointing hand.<br/>
<format color="369650">Change the cursor</format>
to the pointing hand.
</td>
</tr>
<!--
<tr>
<td> Do not address the reader. </td>
<td style="font-style:italic"> Use combobox if..., Follow guidelines... </td>
</tr>
-->
<tr>
<td> When describing user behavior, write 'a user + verb'.</td>
<td> A
<format color="369650">user looks</format>
forward to what will appear after completion.
</td>
</tr>
<tr>
<td> Avoid bracketed text. If information is important, put it out of the brackets or add a new
sentence. Otherwise, remove it.
</td>
<td>Provide a header
<format color="E55765">(bold)</format>
for each progress. <br/> Provide a
<format color="369650">bold</format>
header for each progress.
</td>
</tr>
</table>
</chapter>
<chapter title="Content" id="content">
<list>
<li>
<p>Omit common introductory phrases.</p>
</li>
<li>
<p>Write one idea per sentence.</p>
</li>
<li>
<p>Split the text to subsections and short paragraphs.</p>
</li>
<li>
<p>Use bulleted lists when the order of points does not matter, and numbered list when it does.</p>
</li>
<li>
<p>When giving a recommendation, explain why it is useful:</p>
</li>
</list>
<table>
<tr>
<td width="50%">
<format color="E55765" style="bold">Incorrect</format>
</td>
<td>
<format color="369650" style="bold">Correct</format>
</td>
</tr>
<tr>
<td><p>If a process is started by a user, provide a notification when the process finishes.</p></td>
<td>
<p>If a process is started by a user, provide a notification.
<format color="369650">This way the user will know they can return and see the results.
</format>
</p>
</td>
</tr>
</table>
<list>
<li>Add descriptive links to other sections or websites:</li>
</list>
<table>
<tr>
<td width="50%">
<format color="E55765" style="bold">Incorrect</format>
</td>
<td>
<format color="369650" style="bold">Correct</format>
</td>
</tr>
<tr>
<td><p>Find more details <a anchor="useful-links">here</a>.</p>
</td>
<td><p>Find more details in the <a anchor="useful-links"/></p>
section.
</td>
</tr>
</table>
<chapter title="Tips and notes" id="tips-and-notes">
<p>Use tips <code>&lt;tip&gt;&lt;/tip&gt;</code> to add links to additional materials, sources, useful
facts, and examples:</p>
<tip>Find more examples in <a href="https://www.jetbrains.com/help/writerside/admonitions.html#tip">Writerside
documentation</a>.
</tip>
<p>Use notes <code>&lt;note&gt;&lt;/note&gt;</code> to highlight important information like
exceptions, limitations, or known issues:
</p>
<note>Do not apply this rule to the
<control>New Project</control>
wizard.
</note>
</chapter>
<chapter title="Correct/incorrect/acceptable labels" id="correctincorrectacceptable-labels">
<p>Use the following labels in tables and paragraphs:</p>
<table style="none" border="false">
<tr>
<td>
<p>
<format color="E55765" style="bold">Incorrect</format>
</p>
</td>
<td>
<code-block><![CDATA[<format color="E55765" style="bold">Incorrect</format>]]></code-block>
</td>
</tr>
<tr>
<td>
<format color="369650" style="bold">Correct</format>
</td>
<td>
<code-block><![CDATA[<format color="369650" style="bold">Correct</format>]]></code-block>
</td>
</tr>
<tr>
<td>
<format color="DarkOrange" style="bold">Acceptable</format>
</td>
<td>
<code-block>
<![CDATA[<format color="DarkOrange" style="bold">Acceptable</format>]]></code-block>
</td>
</tr>
</table>
</chapter>
</chapter>
<chapter title="Word-level recommendations" id="word-level-recommendations">
<table>
<tr>
<td>
<format color="E55765" style="bold">Incorrect</format>
</td>
<td>
<format color="369650" style="bold">Correct</format>
</td>
</tr>
<tr>
<td>Avoid using <code>would</code>.</td>
<td> Displaying indicator
<format color="E55765">would be</format>
distracting.<br/>Displaying indicator
<format color="369650">is</format>
distracting.
</td>
</tr>
<tr>
<td> Omit <code>then</code> if possible.</td>
<td> If a process is started by the user,
<format color="E55765">then</format>
provide notification.
</td>
</tr>
<tr>
<td>Replace <code>he</code> or <code>she</code> with <code>they</code>.</td>
<td>If a process lasts less than one second, the user won’t be able to read the process name and
showing it would distract
<format color="369650">them</format>
.
</td>
</tr>
<tr>
<td>Format names of UI elements with <code>&lt;control&gt;&lt;/control&gt;</code>.</td>
<td>Apply the same rule for the
<control>OK</control>
and
<control>Cancel</control>
buttons.
</td>
</tr>
<tr>
<td>Format quotes with <code>&lt;code&gt;&lt;/code&gt;</code>.</td>
<td>Do not use <code>now</code> in button labels.</td>
</tr>
<tr>
<td>
<list>
<li>Format shortcuts with <code>&lt;shortcut&gt;&lt;/shortcut&gt;</code>.</li>
<li>Use a title case for key names and the + sign to connect several keys.</li>
<li>If the shortcuts are different on Windows/Linux and macOS, list all possible variants.
</li>
</list>
</td>
<td>Press
<shortcut>Cdm+Space</shortcut>
on macOS or
<shortcut>Ctrl+Space</shortcut>
on Windows/Linux.
</td>
</tr>
</table>
</chapter>
</chapter>
<chapter title="Code snippets" id="code-snippets">
<p>Provide code snippets along the article to help developers implement the described look and behavior.</p>
<p>If a code snippet is too big, put it at the end of the article and provide a link.</p>
<p>To insert a snippet, use <code>&lt;code-block&gt;&lt;/code-block&gt;</code>. Read more in <a
href="https://www.jetbrains.com/help/writerside/code.html">Writerside documentation</a>.</p>
</chapter>
</topic>