a lot

README.md

@@ -2,20 +2,20 @@
 
 
 ## — What is this?
-This repository is the source code of [**iOS Accessibility Handbook**](https://vodgroup.github.io/AccessibilityDocumentation/documentation/iosaccessibilityhandbook) website, which is an educational resource dedicated to help developers, designers, testers and researchers work on [approachability](https://developer.apple.com/design/human-interface-guidelines/accessibility) of iOS applications.
+This repository is the source code of [**iOS Accessibility Handbook**](https://vodgroup.github.io/AccessibilityDocumentation/documentation/iosaccessibilityhandbook) online documentation, which is an **educational resource** dedicated to help **developers**, **designers**, **testers** and **researchers** work on [**approachability**](https://developer.apple.com/design/human-interface-guidelines/accessibility) of iOS applications.
 
-The book is a collection of **interactive guides** and **thorough articles** permeated with *lots* of **exemplary illustrations** that cover everything one could ever need to know about implementing accessibility.
+The book is a collection of **interactive guides** and **detailed articles** permeated with *lots* of **exemplary illustrations** that cover everything one could ever need to know about **implementing accessibility**.
 
 <img width="876" alt="Screenshot 2024-01-27 at 11 38 37 (2)" src="https://github.com/VODGroup/AccessibilityDocumentation/assets/94866528/3d27a208-0c3f-44db-a4f0-8ecf8691758e">
 
-The material is split into **Chapters** by its relation to a certain topic. The Chapters are joined into **Volumes** by the depth of the knowledge inside. So everyone can find something interesting for themselves *regardless* of their level of expertise.
+The material is split into **chapters** by its relation to a *certain topic*. The chapters are joined into **volumes** by the *depth of the knowledge* inside. This way everyone can find something useful for themselves *regardless* of their level of expertise.
 
 
-## — Who writes this?
+## — Who is responsible of this?
 Majorly the project is based on the content of [**About Accessibility on iOS**](https://rubanov.dev/a11y-book) book written by [**Mikhail Rubanov**](https://github.com/akaDuality). 
 ![prs](./Samples/aboutAccessibility~dark.png#gh-dark-mode-only)
 ![prs](./Samples/aboutAccessibility~light.png#gh-light-mode-only)
-The book is essentially a **complete course** on accessibility of iOS applications, but being a traditional book — moreover available in Russian language exclusively — sucks. So here we are, happily putting videos and samples of code on the pages! Have fun.  
+The book is essentially a **complete course** on accessibility of iOS applications, but being a traditional book — moreover available in Russian language *exclusively* — sucks. So here we are, happily putting **videos** and **code samples** on the documentation pages! Have fun.  
 
 ## — Why make it a website? 
 *Websites* is an exemplary **cross-platform solution**. Having resources available on the Net widens its **availability** — one has to have nothing more than a web browser and an Internet connection to **access the resource**. 
@@ -38,7 +38,7 @@ Yes, **everyone is welcome to influence the project**, especially considering it
 ![prs](./Samples/prs~dark.png#gh-dark-mode-only)
 ![prs](./Samples/prs~light.png#gh-light-mode-only)
 
-- **get in contact with one of the [responsible contributors](https://github.com/VODGroup/AccessibilityDocumentation/graphs/contributors)** by using the *credential information* they've provided.
+- **get in contact with one of the [responsible editors](https://github.com/VODGroup/AccessibilityDocumentation/graphs/contributors)** by using the *credential information* they've provided.
 ![contributors](./Samples/contributors~dark.png#gh-dark-mode-only)
 ![contributors](./Samples/contributors~light.png#gh-light-mode-only)
 

Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Adaption/AdoptionGuide.tutorial

@@ -15,14 +15,14 @@
 
     @Volume(name: "Integrating interfaces with accessibility") {
 
-        This volume covers the **tasks crucial for implementation**: unsolved issues from the inner chapters *exclude* users of [**assistive technology**](<doc:AccessibilityFeatures>).
+        This volume covers the **tasks crucial for implementation**: unsolved issues discussed here *exclude* users of [**assistive technology**](<doc:AccessibilityFeatures>).
 
         @Image(source: placeholder-image.png, alt: "")
 
         @Chapter(name: "Expose interfacial data") {
             @Image(source: chapter-placeholder.png, alt: "")
 
-            First of all, every functional element of the interface has to be sufficiently *described*.
+            First of all, every **functional element** of the interface has to be sufficiently *described*.
 
             @TutorialReference(tutorial: "doc:AccessibleUI")
             @TutorialReference(tutorial: "doc:AccessibilityAttributes")
@@ -34,7 +34,7 @@
         @Chapter(name: "Ensure that navigation is possible") {
             @Image(source: chapter-placeholder.png, alt: "")
 
-            Secondly, to reconnect the elements into a integral interface certain alternative controlling options have to be enabled.
+            Secondly, to *reconnect* the elements into a integral interface certain **alternative controlling options** have to be enabled.
 
             @TutorialReference(tutorial: "doc:OnScreen-Navigation")
             @TutorialReference(tutorial: "doc:FocusManagement")
@@ -44,7 +44,7 @@
         @Chapter(name: "Secure user scenarios") {
             @Image(source: chapter-placeholder.png, alt: "")
 
-            Lastly, to make sure that the users of assistive technology are able to complete the tasks they are supposed to achieve review the layout of the accessible interface.
+            Lastly, to make sure that the users of assistive technology are able to complete the tasks they are *supposed* to achieve we have to **review the layout** of the accessible interface.
 
             @TutorialReference(tutorial: "doc:ControlHierarchy")
             @TutorialReference(tutorial: "doc:Containers")
@@ -54,7 +54,7 @@
 
     @Volume(name: "Providing accessible experience") {
 
-        This volume is dedicated to making the *experience* of [**Accessibility Features**](<doc:AccessibilityFeatures>) users more **comfortable** and **immersive** -- just as it as for regular users.
+        This volume is dedicated to making the *experience* of [**assistive technology**](<doc:AccessibilityFeatures>) users more **comfortable** and **immersive** -- just as it is for "regular" users.
 
         @Image(source: placeholder-image.png, alt: "")
 
@@ -101,7 +101,7 @@
 
     @Volume(name: "Extend on enterprise processes") {
 
-        This volume provides additional insights on the topic of accessibility and its integration at various stages of the product's **life cycle**.
+        This volume provides **additional insights** on the topic of accessibility and its integration at various stages of the **product's life cycle**.
 
         @Chapter(name: "Design") {
             @Image(source: chapter-placeholder.png, alt: "")

Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/AccessibilityFeatures/AccessibilityFeatures.md

@@ -1,10 +1,10 @@
 # Accessibility Features
 
-A brief overview of **Accessibility Features** available on iOS
+A brief overview of assistive technology supported by iOS
 
 @Metadata {
     @PageColor(blue)
-    @TitleHeading("iOS Assistive Technology Stack")
+    @TitleHeading("iOS Accessibility Kit")
     @PageImage(
                purpose: icon, 
                source: "accessibility", 
@@ -19,12 +19,12 @@ A brief overview of **Accessibility Features** available on iOS
                 label: "General Knowledge")
 }
 
-## What is Accessibility Features?
+## -- What is Accessibility Features?
 **Accessibility Features** is a collection of *software* aimed to **help people use the device**. 
 
 @Row {
     @Column {
-       @Image(source: settings-af, alt: "") {
+       @Image(source: settings-af, alt: "Accessibility can be found in Settings") {
        }
     }
    @Column {
@@ -37,13 +37,13 @@ A brief overview of **Accessibility Features** available on iOS
    }
 }
 
-### Accessibility Features Are a Form of Assistive Technology
-**Accessibility Features** are programmed to **personalise user experience** by adjusting the operation system's behaviour to meet users' needs and enable them to use the given device using *external* assistive technology if required. 
+### Assistive technology
+**Accessibility Features** are programmed to **personalise user experience** by adjusting the operation system's behaviour to **meet users' needs** and **enable them to use the given device** using *external* assistive technology if required. 
 
 @Image(source: placeholder-image, alt: "")
 
 
-### Assistive Technology Helps People with Disabilities
+### People with disabilities
 **Assistive technology** is a term that defines software, hardware and combined solutions to make life of **people with disabilities** easier. Every **Accessibility Feature** is an **assistive technology** on its own, but some features are purposed to **support external assistive technology** devices which provide alternative *input* and *output* interfaces for the system. 
 
 @Image(source: placeholder-image, alt: "")
@@ -52,18 +52,18 @@ For example, **control devices** such as **switches** and **keyboards**, **heari
 
 @Image(source: placeholder-image, alt: "")
 
-### iOS Is Accessible from the Start
+### Native accessibility of iOS
 Nevertheless, most of the features that *enhance* approachability of the system do not require anything extrinsic and work **out of the box**. Excluding the possibly needed external devices, *native* accessibility functionality of the iOS devices covers a wide range of needs of users with disabilities.  
 
 @Image(source: placeholder-image, alt: "")
 
-## Accessibility Features on iOS
+## Accessibility Features
 Here is the list of **Accessibility Features** available on iOS. 
 
-@Image(source: features-list, alt: "")
+@Image(source: features-list, alt: "A large text Keynote slide listing Accessibility Features: Dynamic Type, VoiceOver, Zoom, Spoken Content features, Reduce Transparency, Switch Control, Reduce Motion, On and Off labels, AssistiveTouch, Full keyboard access, Voice Control, Bold Text, Pointer Control, Sound Recognition, Guided Access, Dwel Control, Type to Siri, Sound Actions, Button Shapes, Color Filters, Increase Contrast, Hearing Aids")
 
 
-In this book we're not going to take a precise look at each of them separately, but there are features that have to be thoroughly researched to understand the **accessibility of iOS** in general. 
+Though in this book we're not going to take a precise look at each of them separately, but only at the features that have to be **implicitly supported** to *function*. 
 
 @Links(visualStyle: detailedGrid) {
     - <doc:VoiceOver>
@@ -80,27 +80,23 @@ Each article above contains an overview of a feature that explains **what this f
 
 @Image(source: placeholder-image, alt: "")
 
-## Supporting Accessibility Features in Your App
+## Adopting Accessibility Features
 
-[**Accessibility Features**](<doc:AccessibilityFeatures>) use the **semantic language** of an application and change some of its *interfacial* properties to alternate the **usability** of its interface. To see how accessibility is integrated to interfaces proceed to [**Accessible Interface**](<doc:BasicTechniques>) -- the heading article of **Adapting Interfaces** volume, which is purposed to break down the **accessibility adoption** process.
+[**Accessibility Features**](<doc:AccessibilityFeatures>) use the **semantic language** of an application and change some of its *interfacial* properties to alternate the **usability** of its interface. To see how accessibility is integrated to interfaces proceed to [**Accessible Interface**](<doc:AccessibleUI>) -- the heading article of **Adapting Interfaces** volume, which is purposed to break down the **accessibility adoption** process.
 
 @Links(visualStyle: detailedGrid) {
-    - <doc:BasicTechniques>
+    - <doc:AccessibleUI>
 }
 
-@Image(source: placeholder-image, alt: "")
-
-Supporting a particular feature usually fully or partially enables *other* features to be used in the app, but it is important to understand the meaning of specific **accessibility attributes** of **mobile interfaces** to provide the *equal experience*. To know how *user experience* changes with various [**Accessibility Features**](<doc:AccessibilityFeatures>) used visit the [**Accessible Experience**](<doc:AdvancedTechniques>) page, which is a heading article of the detailed volume dedicated to **polishing accessible experience**.
+Supporting a particular feature usually fully or partially enables *other* features to be used in the app, but it is important to understand the meaning of specific **accessibility attributes** of **mobile interfaces** to provide the *equal experience*. To know how *user experience* changes with various [**Accessibility Features**](<doc:AccessibilityFeatures>) used visit the [**Accessible Experience**](<doc:AccessibleUX>) page, which is a heading article of the detailed volume dedicated to **polishing accessible experience**.
 
 @Links(visualStyle: detailedGrid) {
-    - <doc:AdvancedTechniques>
+    - <doc:AccessibleUX>
 }
 
-@Image(source: placeholder-image, alt: "")
-
 ## Have fun!
 
-## Additional Resources 
+## Resources 
 
 ### Apple Accessibility Support Web Page
 https://support.apple.com/accessibility

Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/AccessibilityFeatures/AssistiveAccess/AssistiveAccess.md

@@ -27,7 +27,7 @@ A simplified mode of iOS
 
 The feature is purposed to provide a drastically **simplified UI of the whole system** with help of [**Dynamic Type**](<doc:DynamicType>) and fundamentally different layouts of **adapted apps** to lighten *cognitive load* for those in need. 
 
-@Image(source: aa-promo-1, alt: "")
+@Image(source: aa-promo-1, alt: "Promotional screenshots of Assistive Access presenting the simplified interfaces of Music, Photos and Camera")
 
 ------------------------------------------------------
 
@@ -37,7 +37,7 @@ The feature is dedicated to enable anyone use their device **independently** reg
 
 The technology's task is to **reduce applications functionality** to the point when the possibility that everyone can find app's interface understandable is *maximal*. 
 
-@Image(source: aa-promo-2, alt: "")
+@Image(source: aa-promo-2, alt: "Other promotional screenshots of Assistive Access presenting the simplified interfaces of Home Screen, Calls and Messages")
 
 
 So people who have **cognitive** or **learning impairments** could easily use iPhones *on their own*. 
@@ -80,13 +80,15 @@ To learn more about *reasons* behind these guidelines visit our articles on the
 
 ------------------------------------------------------
 
-## How to adapt your app
+## How to integrate it in your app
 
-@Image(source: aa-adapted, alt: "")
+@Image(source: aa-adapted, alt: "Promotional screenshots of an unknown application supporting Assistive Access")
 
 As for today **Assistive Access** is more of a prototype than a real feature: **there is no comprehensible guidelines (and options at all) of how to *adapt* applications**. 
 
-@Image(source: aa-support, alt: "")
+@Image(source: aa-support, alt: "A screenshot of one of the Assistive Access code properties documentation") {
+    This is not a lie, but is useless.
+}
 
 @Comment {
     https://x.com/akaDuality/status/1722764671806038319?s=20
@@ -100,5 +102,14 @@ Moreover, at the moment there are only **Messages**, **Calls**, **Music**, **Pho
 
 Nevertheless, if **Apple** *decides* that they should invest their resources into proper development of the feature this page is going to turn into a complete guide of how to adapt applications for **Assistive Access**. As for now...
 
-@Image(source: tbc, alt: "")
-
+@Image(source: tbc, alt: "A large text Keynote slide saying \"... to be continued?\"")
+
+## See Also
+- <doc:AccessibilityFeatures>
+- <doc:VoiceOver>
+- <doc:VoiceControl>
+- <doc:SwitchControl>
+- <doc:aDynamicType>
+- <doc:FullKeyboardAccess>
+- <doc:AssistiveTouch>
+- <doc:aGuidedAccess>