Accessibility Readability

Accessibility & Readability Skill

Instructions

1. Reading Level Guidelines

2. Explain Technical Terms

First mention of any technical term MUST include:

**ROS 2** (Robot Operating System 2) is a middleware framework that provides 
tools and libraries for building robot applications. Think of it as the 
"nervous system" that lets different parts of a robot communicate.

3. Glossary Integration

Create docs/glossary.mdx with all terms:

## R

### ROS 2
**Robot Operating System 2** — A middleware framework for robotics development.
- **Used in**: Modules 1, 3, 4
- **Prerequisite for**: Understanding node communication
- **Related**: Topics, Services, Actions

### rclpy
**ROS Client Library for Python** — Python bindings for ROS 2.
- **Installation**: `pip install rclpy`
- **Import**: `import rclpy`

Link to glossary on first use:

We'll use [ROS 2](/docs/glossary#ros-2) to control our robot.

4. Multi-Level Explanations

Provide layered depth for complex topics:

## What is a ROS 2 Node?

### 🟢 Simple Explanation (Beginner)
A node is like a worker in a factory. Each worker (node) has one job, 
and they communicate by passing messages to each other.

### 🟡 Technical Explanation (Intermediate)
A node is an independent process that performs computation. Nodes 
communicate via topics (pub/sub), services (request/response), or 
actions (long-running tasks with feedback).

### 🔴 Deep Dive (Advanced)
Nodes are executables within a ROS 2 package. They use DDS (Data 
Distribution Service) for communication, with QoS (Quality of Service) 
policies controlling reliability, durability, and history.

5. Prerequisite Mapping

Every chapter must clearly state what knowledge is assumed:

## 📋 Prerequisites

**Required Knowledge:**
- ✅ Basic Python (variables, functions, classes)
- ✅ Command line basics (cd, ls, mkdir)
- ✅ [Chapter 1.1 — Introduction to Physical AI](/docs/module-1/week-1-2/)

**Helpful but Optional:**
- ⭕ Linux system administration
- ⭕ Previous robotics experience

**You'll Learn Here:**
- 🆕 ROS 2 node creation
- 🆕 Publisher/subscriber pattern

6. Code Accessibility

Always explain code step-by-step:

```python
# Step 1: Import the ROS 2 Python library
import rclpy
from rclpy.node import Node

# Step 2: Create a class that inherits from Node
class MyNode(Node):
    def __init__(self):
        # Step 3: Initialize the parent class with a node name
        super().__init__('my_node')  # 'my_node' is visible in ROS tools
        
        # Step 4: Log a message to confirm the node started
        self.get_logger().info('Node has started!')

Line-by-line breakdown:

### 7. Visual Learning Aids

For each major concept, include:

1. **Analogy** — Real-world comparison
2. **Diagram** — Visual representation
3. **Code** — Working example
4. **Exercise** — Hands-on practice

```mdx
## Understanding Topics

### 🎯 Analogy
Topics are like radio channels. Publishers broadcast on a channel, 
and any subscriber tuned to that channel receives the message.

### 📊 Diagram
```mermaid
graph LR
    P[Publisher] -->|broadcasts| T[/topic_name]
    T -->|receives| S1[Subscriber 1]
    T -->|receives| S2[Subscriber 2]

💻 Code Example

[See code block above]

✍️ Exercise

Create a publisher that sends your name every second.

### 8. Accessibility Standards

**Images:**
```mdx
![Diagram showing ROS 2 node communication with arrows between publisher and subscriber nodes](/img/ros2-nodes.svg)

Color contrast: Don't rely solely on color

✅ Good: "The green checkmarks (✅) indicate success"
❌ Bad: "Green items are complete"

Keyboard navigation: Ensure all interactive elements are accessible

9. Progress Indicators

Help learners track their journey:

## 📍 Your Progress

| Module | Status | Completion |
|--------|--------|------------|
| Module 1: ROS 2 | 🟢 Current | 60% |
| Module 2: Simulation | ⚪ Upcoming | 0% |
| Module 3: Isaac | ⚪ Upcoming | 0% |
| Module 4: VLA | ⚪ Upcoming | 0% |

**Estimated time to complete this chapter:** 45 minutes

10. Recap Sections

End each major section with a quick recap:

## 🔄 Quick Recap

**What we covered:**
- ✅ Created a ROS 2 node using Python
- ✅ Published messages to a topic
- ✅ Subscribed to receive messages

**Key commands:**
```bash
ros2 run my_package my_node    # Run a node
ros2 topic list                 # List all topics
ros2 topic echo /topic_name    # View messages

Common mistakes to avoid:

• ❌ Forgetting to call rclpy.init() before creating nodes
• ❌ Not spinning the node (rclpy.spin(node))

## Validation Checklist

- [ ] All technical terms defined on first use
- [ ] Glossary entries for domain-specific terms
- [ ] Multi-level explanations for complex topics
- [ ] Prerequisites clearly stated
- [ ] Code explained line-by-line for beginners
- [ ] Images have descriptive alt text
- [ ] Estimated reading time provided
- [ ] Quick recaps at section ends

## Definition of Done

- Content passes readability check for target audience
- All technical terms linked to glossary
- Beginner/intermediate/advanced sections where appropriate
- Every code block has explanatory comments
- Accessibility standards met (alt text, contrast, etc.)