Update ROS 2 real-time documentation

[carlossvg]

Hi @clalancette, as part of the RTWG we are planning to update ROS 2 real-time documentation.

The plan, as explained in https://github.com/ros-realtime/community/issues/41#issuecomment-1424128043, is to migrate some of already existing docs from https://ros-realtime.github.io/ to https://docs.ros.org/. Before creating a PR we would like to get some feedback about the best way to add the mentioned changes. Specifically, we would like to know which option would be better:

1. Create one PR to updated all the related documents
2. Split the work to multiple PRs, so it is better digestible for review.

FYI @JanStaschulat @razr @nightduck

[clalancette]

The plan, as explained in ros-realtime/community#41 (comment), is to migrate some of already existing docs from https://ros-realtime.github.io/ to https://docs.ros.org/.

Before we start migrating, what is the overall goal here? Why do we want to move this into the main ROS 2 documentation? What about linking to the realtime documentation from the Related-Projects section? Would that work?

[JanStaschulat]

Hi @clalancette, our goals for consolidating the real-time documentation are:

• One entry point. Currently, there are bits and pices all over the place. Some information is in Tutorials, some is in HowTos on docs.ros.org, while other is hosted on RTWG space. The goal is to have an entry point (e.g. Tuturials/Advanced/Real-Time) with some sub-pages, like Tutorials/Advanced/Security. Those pages could then have links to RTWG pages.
• Add missing documentation. For example, about which features of ROS 2 could be used to improve the real-time capabilities of an application. ROS 2 provides many features, like Executors and callback groups. But there is no tutorial how to combine this with real-time multi-threading (e.g. by using multiple threads of the operating system with different priorities). The multi-threaded Executor does not provide any means to prioritize callback processing. We want to write a new tutorial about this.
• Improve searchability. The reason to move some real-time documentation, which is currently hosted on ros-realtime.github.io, to docs.ros.org is, that users would be able to find documentation about real-time more easily. Many user might not be aware of the ros-realtime.github.io pages. On the other hand, if someone searches today for "real-time" on docs.ros.org, there are 33 results. However, many un-related pages are listed while information about how to actually develop a real-time application is not available. Questions like: What is possible with ROS 2? Does it give guarantees? What are best-practices? are un-answered.

Sure, it would be great to add https://ros-realtime.github.io to Related-Projects, this would already help to improve searchability, but would not achieve all goals.

[JanStaschulat]

Specifically, we propose to:

1. move one tutorial about "ROS 2 Tracing" from ros-realtime to mainline
2. create a subsection “Real-Time” under “Tutorial/Advanced” with two new Tutorials about Real-Time Development
3. add one page under Concepts with some Background information about Real-Time in ROS 2.

See here for more details.

[fujitatomoya]

@JanStaschulat @carlossvg @clalancette

Basically I will second this, having Real-Time related documentation for end users will be useful. and entry point should be linked to here to guide the Real-TIme users from central documentation site.

Here are my questions and opinions,

• if the Tutorial is not requiring special system configuration such as RT patch (only having vanilla ubuntu and install ROS 2 binary packages), that said general Real-Time tutorial with ROS 2 that enhances Real-Time capability for the application, i think it can be in Tutorial/Advanced in here.
• if the Tutorial is requiring special system configuration, maybe that should be aligned with Real-Time set up procedure in Real-Time documentation site. I would think for those users, they would probably have a scope for Real-Time system before this Tutorial, so it would be better that we have these documentation under Real-Time documentation site as well? if i were reading this doc, this would be probably more user-friendly structure to avoid jumping back and forth documentation sites.
• ROS 2 Tracing can be in main doc site, off topic from Real-Time? I believe Tracing capability and Real-Time is not really connected directly. and besides, these tracing points are already integrated in the core libraries.

What about linking to the realtime documentation from the Related-Projects section? Would that work?

at least this makes sense to me, not to scatter the ROS 2 documentation.

[christophebedard]

• ROS 2 Tracing can be in main doc site, off topic from Real-Time? I believe Tracing capability and Real-Time is not really connected directly. and besides, these tracing points are already integrated in the core libraries.

Yeah, I can take care of moving the existing tutorial from ros-realtime.github.io (here) to docs.ros.org separately.

[clalancette]

• if the Tutorial is not requiring special system configuration such as RT patch (only having vanilla ubuntu and install ROS 2 binary packages), that said general Real-Time tutorial with ROS 2 that enhances Real-Time capability for the application, i think it can be in Tutorial/Advanced in here.

That seems reasonable. That said, there is also https://github.com/ros2/realtime_support/issues/123 , where we are trying to spin realtime support out of the core, so I want to be consistent.

• if the Tutorial is requiring special system configuration, maybe that should be aligned with Real-Time set up procedure in Real-Time documentation site. I would think for those users, they would probably have a scope for Real-Time system before this Tutorial, so it would be better that we have these documentation under Real-Time documentation site as well? if i were reading this doc, this would be probably more user-friendly structure to avoid jumping back and forth documentation sites.

Yeah, I think for these things we want to put them on the ros-realtime site.

• ROS 2 Tracing can be in main doc site, off topic from Real-Time? I believe Tracing capability and Real-Time is not really connected directly. and besides, these tracing points are already integrated in the core libraries.

Yeah, agreed, and it looks like Christophe is already on this.