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:

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('mynode') # 'mynode' 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:**
| Line | Purpose |
|------|---------|
| `import rclpy` | Load the ROS 2 Python library |
| `from rclpy.node import Node` | Import the base Node class |
| `class MyNode(Node)` | Create our custom node |
| `super().__init__('my_node')` | Register with ROS 2 |
| `self.get_logger().info(...)` | Print to ROS 2 logging system |

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

## Understanding Topics

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

### 📊 Diagram

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:

![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:**

ros2 run mypackage mynode # 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.)