Documentation

Documentation – definition

In mobile robotics, documentation is the structured set of technical materials that describe how a robot platform, software stack, interface, or component is specified, configured, operated, maintained, and extended. It includes normative definitions, API references, hardware specifications, integration instructions, examples, and operational constraints. In a ROS and ROS 2 context, documentation also covers message definitions, coordinate frame conventions, launch and parameter schemas, package dependencies, and lifecycle behavior.

For UGV platforms, documentation is not only descriptive. It is part of system reliability and reproducibility. A mobile robot integrates mechanical, electrical, embedded, and software layers. If one layer is undocumented, integration risk rises. In practice, good documentation allows an engineer to answer concrete questions: what voltage range a payload port supports, which ROS 2 topic publishes wheel odometry, what frame_id a LiDAR driver uses, how IMU covariance should be set, or which Ubuntu and ROS 2 distribution are supported by the onboard computer.

For Fictionlab platforms such as Leo Rover and Raph Rover, documentation is the primary source for safe setup and repeatable development. Leo Rover documentation is relevant for researchers and students who need to bring up ROS 2 nodes, connect sensors, and build autonomy functions on a Raspberry Pi-based platform. Raph Rover documentation is especially important in payload-heavy and field integration scenarios, where power budget, mounting interfaces, communication buses, and compute architecture must be described precisely.

What documentation includes in robotics

Documentation in robotics usually spans several layers. Each layer answers a different engineering question. In UGV projects, these layers should stay aligned with the actual hardware and software revision deployed on the robot.

System documentation – architecture overview, supported use cases, network topology, safety limits, maintenance procedures.
Hardware documentation – dimensions, mass, ingress protection, connector pinout, supply voltage, current limits, encoder specification, motor controller interfaces.
Software documentation – package purpose, dependencies, launch files, parameters, topics, services, actions, QoS behavior.
API documentation – public interfaces, message fields, units, valid ranges, return codes.
Operational documentation – flashing procedure, calibration steps, troubleshooting, logs, firmware update path.
Developer documentation – build instructions, Docker workflow, CI rules, contribution guidelines, test coverage.

In ROS 2, documentation should also describe how a node interacts with the graph. That means topic names, message types, services, actions, TF frames, parameter defaults, namespaces, and remapping assumptions. Without this, packages may compile but still fail in integration.

Documentation in ROS and ROS 2

ROS documentation is partially standardized through package structure, message definitions, and REP conventions. ROS 2 documentation on docs.ros.org defines core concepts such as nodes, topics, services, actions, parameters, lifecycle nodes, and DDS-based communication. In practice, a robotics team should document both upstream ROS behavior and project-specific assumptions.

Several ROS conventions directly affect documentation quality:

REP 103 – standard units of measure and coordinate conventions. It defines SI units and common axis orientation rules.
REP 105 – coordinate frames for mobile platforms, including frames such as base_link, odom, and map.
URDF and related robot description files – kinematic structure, links, joints, inertial and collision properties.
sensor_msgs, nav_msgs, geometry_msgs – message contracts that should be documented with frequency, frame_id, and covariance assumptions.

For example, wheel odometry documentation should not stop at saying that odometry exists. It should define the topic name, message type, expected rate, source, and limitations. A useful specification looks like this:

Topic: /odom
Type: nav_msgs/msg/Odometry
Rate: 20-50 Hz
Frame IDs: header.frame_id=odom, child_frame_id=base_link
Source: differential drive wheel encoders
Limitation: drift accumulates without external correction

In ROS 1 and ROS 2, names and APIs may differ even when concepts are similar. Documentation must state the exact distribution. For example, ROS 2 Humble and newer systems may rely on Nav2, lifecycle nodes, and DDS QoS settings that do not exist in ROS 1 in the same form.

Key quality attributes of technical documentation

For robotics teams, documentation quality can be assessed against a small set of technical criteria. These criteria matter more than writing style.

Attribute	What it means	Why it matters on UGVs
Accuracy	Matches the actual hardware and software revision	Wrong pinout or topic name causes integration failure
Completeness	Covers interfaces, limits, and procedures end to end	Missing calibration step may break localization
Versioning	States release, firmware, ROS distro, and package version	Behavior differs between Humble, Iron, and Jazzy
Traceability	Links claims to source specs, REPs, or code	Useful in research and regulated test environments
Reproducibility	Allows another engineer to rebuild and run the system	Critical for labs, field tests, and student projects

A practical rule is simple: every interface should be documented with type, unit, rate, valid range, and failure mode. This is especially important for sensor integration.

Examples for Leo Rover and Raph Rover

On Leo Rover, documentation often focuses on bring-up, ROS 2 support, sensor mounting, and lightweight compute constraints. Since Leo Rover uses a Raspberry Pi-based compute unit and supports ROS 2, documentation should state supported images, OS version, ROS 2 distribution such as Humble, and expected resource usage for nodes such as SLAM, Nav2, or camera drivers. It should also explain that Leo Rover is a 4-wheel skid-steer platform and that autonomy requires an additional navigation stack and sensor integration.

On Raph Rover, documentation typically goes deeper into payload integration. A larger UGV must document payload mass limits, power distribution, communications, mechanical interfaces, and sensor synchronization assumptions. In field robotics, undocumented power peaks, GNSS antenna placement, or LiDAR frame misalignment can invalidate experiments.

Good platform documentation should answer questions like these:

Which TF tree is expected from the base platform?
What odometry source is available by default?
Which ports are intended for USB LiDAR, GNSS, or depth camera integration?
What is the supported ROS 2 launch workflow for teleoperation, SLAM, and navigation?

Minimal documentation examples

Robotics documentation becomes much more useful when it includes executable examples. For ROS 2, this usually means launch snippets, parameter files, and CLI inspection commands.

ros2 topic list
ros2 topic info /scan
ros2 interface show sensor_msgs/msg/LaserScan
ros2 param list /controller_server
ros2 run tf2_tools view_frames

lidar_node:
  ros__parameters:
    frame_id: laser_frame
    serial_port: /dev/ttyUSB0
    angle_compensate: true
    scan_mode: Standard
    inverted: false

The value of such examples is that they reduce ambiguity. An engineer can compare the documented interface against the live robot and detect mismatches quickly.

Documentation as part of research reproducibility

In academic robotics, documentation is closely tied to reproducibility. A published result based on SLAM, navigation, or perception should state the robot platform, wheel geometry, sensor model, topic rates, synchronization strategy, and software version. IEEE-style rigor requires that methods can be inspected and repeated. In ROS 2 systems, this often means preserving package versions, configuration files, bag data format, and launch procedures.

This is one reason official documentation sources matter. ROS documentation, REP standards, and manufacturer specifications are stronger references than informal examples. For Leo Rover, the technical documentation at docs.fictionlab.io should be treated as the primary implementation reference. Additional component-level claims should be traced to upstream vendor specifications, for example for Intel RealSense cameras, Slamtec LiDARs, NVIDIA Jetson modules, or GNSS/RTK receivers.

Common failures caused by poor documentation

Many UGV integration issues are documentation issues in disguise. The hardware may work and the ROS graph may run, but the system still fails because assumptions are hidden or inconsistent.

Frame conventions do not follow REP 103 or REP 105.
Topic names changed between package versions without update notes.
Sensor rates are undocumented, so downstream filters are tuned incorrectly.
URDF and real hardware dimensions diverge, which breaks localization and simulation consistency.
Power and thermal limits are omitted, leading to unstable operation in field deployments.

In short, documentation in mobile robotics is a technical interface, not a secondary artifact. It defines how engineers understand and trust a robot platform. On Leo Rover and Raph Rover, good documentation reduces bring-up time, improves repeatability, and lowers integration risk across sensors, ROS 2 packages, and custom autonomy stacks.