# Articles Structure, Styling, and Formatting

## Language, Grammar, and Tone

* Use American English when creating articles. Most of our clients use this type of English and would prefer to have articles written in the language variation they understand best. You may check the main differences [here](https://www.enago.com/documents/resources/BrE-AmE.pdf).
* Use short, simple, easy-to-understand words and sentences, but avoid the overuse of such sentences as it reflects poorly on the writer and gives the writing an informal tone.
* Avoid the passive voice, except where appropriate. In general, use the present tense and, where appropriate, the imperative mood (“Do this.”). Use strong subject-verb constructions. Be concise; avoid wordy phrases.
* Use interrogative sentences only if there is a great need.
* In most cases, it’s appropriate to use the second-person (you, yours) point of view, because it’s friendly and easy to understand.

___

## Structure

* Each article should start with an introduction followed by a table of contents.
* In table of contents avoid using many sub-paragraphs or sub-items like a) or 1.1 or 1.1.1. It should be accurate and easy to read.
* Divide major large article sections into shorter subsections where needed. When subsections are too short, try to combine them in one section. Avoid one sentense paragraphs.

___

## Capitalization

* During the titles capitalization, stick to APA capitalization. If you are unsure how to capitalize your title, use [this checker](https://capitalizemytitle.com/) for help.
* Capitalize the first letter of the first word of the list item.
* Dropdown elements
* Use Capitalization for UI Elements similar to UI elements.
> Capitalize every first letter of each word in the UI element name, regardless of its capitalization in the UI. Example: **SIGN IN** or **Sign in** should always be transfored into **Sign In**. -> Thats is still my point. But guyz didn't want to accept this regardless of any shown guides and recommendations. As an example --- https://www.microsoftpressstore.com/articles/article.aspx?p=2228449&seqNum=15

___

## Font Styles

* Use **Bold** to highlight the UI elements user interacts with or the hotkeys to press.
* Use ```developer text formatting``` for code snippets and command line examples.
* Use ":" only in regular sentences or in the call to action before the list of actions
* Use *Italic* to hightlight Objects, Fields, exact values for inputs, and to emphasize (try to avoid)

## En Dash vs Em Dash vs Hyphen

Dashes and hyphens aren't interchangeable. Follow these guidelines to help you use them the right way, in the right places.

[Em dashes](https://learn.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/emes). Use to set off or emphasize parenthetical phrases.

[En dashes](https://learn.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/enes). Use in ranges of numbers and dates, in negative numbers, and as a minus sign. Use to connect compound modifiers under specific conditions.

[Hyphens](https://learn.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/hyphens). Use to join words and connect prefixes to stem words. Don't use two hyphens in place of an em dash.

___
## Lists

* Use a numbered list for procedures or other sequential lists. Introduce a procedure with a sentence in the imperative mood.
* Use a bulleted list for an unordered series of concepts, items, or options. Capitalize the first word of each bulleted entry.
* End each list item with a dot when the list item is a sentence. Do not use dot when when that's a list of words (not sentences). When we have a mox of both --- put dot.

___

## User Interface Syntax

The following terms are most commonly used to describe how users interact with controls and commands:

- *Click*: Use for commands, command buttons, option buttons, and options in a list, gallery, or palette.
- *Select and clear*: Use for check boxes.
- *Type or select*: Use to refer to an item that the user can either type or select in the accompanying text box. You can use *Enter* instead if there is no possibility of confusion.

Except for the identifiers *box, list, check box*, and *tab*, the generic name of a control (*button, option,* and so on) should not follow the label of a control, especially within procedures.

Use bold formatting for dialog box titles, labels, and options. Do not use bold formatting for the title of a webpage. Instead, insert a hyperlink if appropriate or use regular type.

___

## Navigation Elements

For naviagation arrows use -> as an arrow sign.
___

## Screenshots

* Any screenshot in the article should be clear, perfectly visible.
* Make UI screenshots size for them to take the whole space (width) of the doc sreen.
* Make maximum possible resolution of screenshots (2x size like retina screenshots if possible).
* If you use arrows or shapes (like rectangles, ellipses or rounded rectangles) to highlight some text or button on the screenshot, choose green color for highlighting. Prior to applying any changes to the screenshot, save the original screenshot without any highlighting.
* Please make the arrows and shapes as minimalistic as possible
* In the multi-step instructions, create GIFs instead of a screenshot for each step.

___