formatting of describeElements

Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/DescribeElements.md

@@ -1,27 +1,27 @@
 # Describing Elements
 
-In this article we're going to go over core properties that describe elements for assistive technologies.
+In this article we're going to go over core *properties* that **describe *elements* for assistive technologies**.
 
-Elements description is an essential part for the functioning of VoiceOver. This technology is aimed to tell users what's happening on the screen.
+Elements *description* is an essential part for the functioning of **VoiceOver**. This technology is aimed to ***tell* users what's happening on the screen**.
 
-Nevertheless Voice Control and Switch Control also benefit from explicitly stated decriptional properties in particular cases.
+Nevertheless **Voice Control** and **Switch Control** also benefit from explicitly stated descriptional *properties* in particular cases.
 
-To describe an element we can specify three properties: a label, a value and a trait. Let's get familiar with each of them.
+To describe an element we can **specify three properties**: a *label*, a *value* and a *trait*. Let's get familiar with each of them.
 
 
-## Label
+## `accessibilityLabel` — Label
 
 @Row {
     @Column(size: 1) {
         ``Book/accessibilityLabel``
 
-        `accessibilityLabel` is the main property of the element's description. It can't be omitted. Usually defines the element's name. 
+        `accessibilityLabel` is the *main* property of the element's description. **It can't be omitted**. Usually **defines the element's *name***. 
 
-        If the element is a button it should be labeled by a single word or a collocation. 
+        If the element is a *button* it should be **labeled by a *single word* or a *collocation* that represent the *action* it does**. 
 
-        If there is text in `UILabel` it should be copied to `accessibilityLabel`.
+        If there is *text* in `UILabel` it should be copied to `accessibilityLabel`.
 
-        > Tip: Voice Control can use a list of synonyms as the same label. It is done so users may address to a single element by multiple options. Check ``Book/accessibilityUserInputLabels`` for more details.
+        > Tip: **Voice Control** can use **a list of synonyms as its label**. It is done so users may ***address* to a single element by multiple options**. Check ``Book/accessibilityUserInputLabels`` for more details.
     }
 
     @Column {
@@ -37,27 +37,20 @@ To describe an element we can specify three properties: a label, a value and a t
     }
 }
 
-## Value
+## `accessibilityValue` — Value
 
 @Row {
     @Column(size: 2) {
         ``Book/accessibilityValue``
 
-        `accessibilityValue` is an optional property of the element's description. Unlike Label it can be omitted. It is used to provide additional informational.
+        `accessibilityValue` is an *optional* property of the element's description. Unlike *Label* it can be omitted. It is used to **provide *additional* information**.
 
-        > Note: If stated, Label and Value are separated by a comma in speech — VoiceOver will put a pause between them on its own.
+        > Note: If stated, *Label* and *Value* are **separated by a comma** in speech — **VoiceOver** will put a *pause* between them on its own.
 
-        > Tip: But everything that happens inside the properties in terms of pronunciation is our responsibility. Don't forget to use punctuation marks to help VoiceOver read texts better for humans to hear.
+        > Tip: But everything that happens inside the properties in terms of **pronunciation** is *our* responsibility. **Don't forget to use *punctuation marks* to help VoiceOver read texts *easier* for humans to listen to**.
     }
 
     @Column {
-        **Examples:**
-        - *1.4 billions views* – no value for regular text is ofter situation
-        - *Never Gonna Give You Up, **Rick Astley*** 
-        - *Next, **Childish Gambino – Redbone*** – can add detalization about next track. Visually you can see a cover of the song, but for VoiceOver it is better to provide text alternative. Different approaches, but same experience.
-        - *Pizza Pepperoni, **Pepperoni, Mozzarella***
-        - *Size, **Medium***
-
         **Same examples:**
         - *1.4 billions views* does not have any additional information so no value. Label is enough.
         - *Never Gonna Give You Up* may have a lot of additional information: the author, the album, the year and so on.
@@ -71,33 +64,31 @@ To describe an element we can specify three properties: a label, a value and a t
 
 
 
-### Label vs Value
+### Label vs Value: What's The Difference?
 
-It is important to clearly differentiate Label and Value in order to properly adapt the element for various Accessibility Features. 
+It is important to **clearly differentiate *Label* and *Value* in order to properly *adapt* the element for various Accessibility Features**. 
 
-For example, label should be as short as possible for Voice Control: it will be used as HUD over UI to use the feature's voice commands and there is no reason to double any other information available on the screen. <doc:Voice Control>
+For example, *Label* should be **as short as possible** for **Voice Control**: it will be used as a HUD over the UI to use the feature's *voice commands* and **there is no reason to *double* any other information already available on the screen**. <doc:Voice Control>
 
-Another example is Adjustable Elements: this features will change only the value part, so if you want to use it you have to have everything changable outside Label property. <doc:AdjustableElements>
+Another example is **Adjustable Elements**: this feature will change *only* the *Value* part, so if you want to use it you have to **have everything changable outside the *Label* property**. <doc:AdjustableElements>
 
-## Trait
+## accessibilityTraits — Traits
 
 @Row {
     @Column(size: 2) {
         ``Book/accessibilityTraits``
 
-        `accessibilityTraits` is another optional property of the element's decription. Traits are used to point at the element's type — depending on the type the feature's behavior may change. 
+        `accessibilityTraits` is another *optional* property of the element's decription. *Traits* are used to **point at the element's *type*** — **depending on the type the feature's *behavior* may change**. 
 
-        If there is no trait specified it would mean that the element is of a regular text type.
+        If there is *no* trait specified it would mean that the element is of a **regular text** type.
 
-
-        The most common trait that you're going to work with is ``UIAccessibilityTraits_/button`` — it's presence is a sign of an interactive element. 
+        The *most* common trait that you're going to work with is ``UIAccessibilityTraits_/button`` — it's presence is a sign of an *interactive element*. 
 
-        If there is a button in the interface but it is not specified in its description — users will be able to interact with this elements using Accessibility Features.        
+        **If there is a *button* in the interface but it is not specified in its description — users *won't* be able to interact with this element using Accessibility Features**.        
 
-        > Note: If Label and Value are separated by comma, Trait is separated from the other parts of the description by a full stop. 
-        > Important: Label and Value are `String` properties, but Trait can be selected only from limited amount of variants.
-        
-        > Important: Don't mention Trait inside Label or Value. There is no need to double up such facts for users: if the element is a button they will know everything they need to know depending on the Accessible Feature used.
+        > Note: If *Label* and *Value* are separated by a *comma*, *Trait* is separated from the other parts of the description by a *full stop*. 
+        > Important: *Label* and *Value* are `String` properties, meanwhile *Trait* is **selected from a *limited* amount of options**.
+        > Important: **Don't mention *Trait* inside *Label* or *Value***. There is **no need to *double up* such facts for users: if the element is, for example, a *button*, they will know *everything* they need to know** depending on the **Accessible Feature** used.
     }
 
     @Column {
@@ -116,11 +107,12 @@ Another example is Adjustable Elements: this features will change only the value
 **Samples:**
 
 
-## Hint
+## `accessibilityHint` — Hint
 ``Book/accessibilityHint``
 
-Hint is another optional property that is used to provide additional information about the element itself. Property's name points at that: we give a hint to the user about how to treat the element. For example, tap twice to active.
-Every default button has a repetitve hint and such behavior results in that majority of VoiceOver users disable that, so you can't expect that many people will see your customised hint. Though there is always a chance that curious users will turn them on for a new app while using <doc:Rotor>: to see how well the application is adapted.
+**Hint** is another *optional* property that is used to **provide additional information about the element itself**. Property's *name* points at that: **we give a *hint* to the user about how to *treat* the element**. For example, «*tap twice to activate*».
+
+> Important: Every *default* button has a *repetitve* Hint and such behavior results in that **majority of VoiceOver users disable that**, so you can't expect that many people will see your *customised* Hint. Though there is always a chance that curious users will turn them on for a new app while using <doc:Rotor>: **to see how well the application is *adapted***.
 
 @Comment {
     // TODO: Describe hint
@@ -148,6 +140,6 @@ Traits that add additional text:
 - ``UIAccessibilityTraits_/searchField``
 - ``UIAccessibilityTraits_/image``
 
-Other traits can add text to diferent place in description
+Other traits can add text to different place in description
 - ``UIAccessibilityTraits_/selected``
 - ``UIAccessibilityTraits_/notEnabled``

Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial

@@ -1,13 +1,13 @@
-@Tutorials(name: "How To Adapt Your application") {
+@Tutorials(name: "How To Adapt an iOS Application") {
     @Intro(title: "Just A Few Steps") {
 
-        To make an application accessible for the assistive technology and therefore allow people with Accessibility Features enabled comfortably use it one doesn't have to do much. The adaptation plan is as simple as:
+        To make an application *accessible* for the *assistive technology* and therefore *allow* people with Accessibility Features enabled comfortably use it one doesn't have to do much. The *adaptation plan* is as simple as:
 
-        1. Simplify and group elements in UI's hierarchy
-        2. Add labels to elements
-        3. Add additional properties
+        1. *Simplify* and *group* elements in the UI's hierarchy
+        2. Add *labels* to elements
+        3. Specify additional *properties*
 
-        Yep, that's it. In other words the adaption process is consisted of an optional reconstructing of already-existing elements' order and their description with some flags explicitly specified.
+        Yep, that's it. In other words **the adaption process is consisted of an optional *reconstructing* of already-existing elements' *order* and their *description* with some *properties* being *explicitly specified***.
 
 <!--        @Image(source: <#file#>, alt: "<#accessible description#>")-->
     }
@@ -31,7 +31,7 @@
         }
     }
 
-    @Volume(name: "Climbing higher") {
+    @Volume(name: "Climbing Higher") {
         @Chapter(name: "Adjustable Elements") {
             Simplifies navigation and control over a complex element for VoiceOver
 
@@ -52,23 +52,4 @@
     @Comment {
         // TODO: Update links
     }
-
-    @Resources {
-        Explore more resources for learning about sloths.
-
-
-        @Videos(destination: "https://www.example.com/sloth-videos/") {
-            Watch cute videos of sloths climbing, eating, and sleeping.
-
-
-            - [Treetop Breakfast](https://www.example.com/sloth-videos/breakfast/)
-            - [Slow Ascent](https://www.example.com/sloth-videos/climb/)
-            - [Rest Time](https://www.example.com/sloth-videos/snoozing/)
-        }
-
-
-        @Downloads(destination: "https://www.example.com/images/sloth-wallpaper/") {
-            Download the cutest sloth wallpaper for your iPhone, iPad, or Mac.
-        }
-    }
 }