ROS 2 documentation suggestions

[mjeronimo]

Guides/Developing-a-ROS-2-Package.html

• "Creating a package" - "in your workspace (usually ~/ros2_ws/src)". I would expect your workspace would be named after your project. For example, "nav2_ws" or "carma_ws."

Guides/Developing-a-ROS-2-Package.html

• "C++ Packages" - "to create executable nodes and link dependencies." Probably helpful to also mention that it also automatically handles include dirs. This could avoid a potential misunderstanding and redundant code in CMakefiles.

index.html

• Under "Where to start" and in the index on the left of the page, "Concepts" are listed after Tutorials and Guides, even though the Concepts bullet section mentions: "Concepts are high-level explanations and background information on core ROS2 concepts, which should provide some context for topics covered in the tutorials." If they are helpful for providing context for the tutorials, shouldn't they be read before the tutorials? Or, is the approach to reference them when needed?

index.html

• The "Contributing" bullet section mentions, "..for contributing new ROS 2 content...". I tend to think of "content" as documentation or something other than code. However, I think that the content mentioned here also includes code. Could clarify that all contributions (code and non-code) are welcome.

index.html

• The text under the "About ROS 2" section mentions, "If you're interested in the business and advancement side of the ROS 2 project,...". Looking at the bullet items, it seems that only "Project goverance" and "Marketing materials" really only related to that topic. The other items are really more about technical details of ROS 2. I would've split the technical items out into a subsequent section.

Tutorials/Configuring-ROS2-Environment.html

• "Background" - "Subsequent local workspaces are called overlays" - It seems to me that what's an "overlay" and what's an "underlay" depend on your point of view. For example, from the perspective of Nav2, everything sourced before nav2 is the "underlay" while nav2 is the "overlay."

Guides/Installation-Troubleshooting.html

• 'General' section (applying to all platforms) - Mentions updating your firewall configuration using ufw and sudo, which are not applicable to Windows. This needs to be restructured so that the General information is indeed general.

Concepts/About-Different-Middleware-Vendors.html

• "Supported RMW implementations" - "Default middlware since Galactic." This seems to imply that Cyclone is the default middlware provider starting with Galactic. Or, will there be a selection process for each release. If so, I recommend the text be: "Default middleware for Galactic."

Concepts/About-Different-Middleware-Vendors.html

• "Default RMW implementation" - "...the default RMW implementation since Galactic is selected as Cyclone DDS if it’s available." This can be made more concise. How about, "...the default RMW implementation is Cyclone DDS." The next sentence mentions what happens if it is not installed, so "if it's available" does have to also be in the first sentence.

Concepts/About-Composition.html

• "Using Components" - This section could be organized as "Compile time", Launch time", and "Run time"

Concepts/About-Client-Interfaces.html

• "The rclpy Package" - "by using the rcl API in the implementation it stays consistent with the other client libraries in terms of feature parity and behavior." It helps with feature parity but is not suffient to ensure feature parity; there is much that still has to happen in rclpy itself.

[Aut0R3V]

Hey, I would like to work on this, I'll start working right away

[audrow]

That'd be great @Aut0R3V - feel free to @ me as a reviewer!

[pr-db]

Hi, is this still open? I'd like to contribute to this.

[clalancette]

Hi, is this still open? I'd like to contribute to this.

This is still open, so feel free to contribute. I'll suggest doing a separate pull request for each of the items, so that it is easier to review.

[songyuc]

Hi, ls is not going to work on Win10-CMD terminal. So, could please improve this, enter ls in the workspace root (~/ros2_ws)?
Maybe dir command can be used to work on Win10-CMD terminal.

[clalancette]

Please consider submitting a pull request to add that, we are happy to review it.

[songyuc]

Hi, @clalancette! I am new to ROS2, and I want to know which branch of ros2_documentation I should fork?

[clalancette]

Hi, @clalancette! I am new to ROS2, and I want to know which branch of ros2_documentation I should fork?

The rolling branch is where we do the main development for the documentation. If you submit a pull request targeting that, we will then have the bot automatically backport it to the other branches. Thanks!

[prateekbhaisora]

Hi, I am new to ROS2 Contributions. I have been using ROS-2 Humble Hawksbill LTS for a month now and want to contribute back to the community. I hope this is still open for contribution?
Also, if anyone else is also working on the same, feel free to connect.

[clalancette]

Hi, I am new to ROS2 Contributions. I have been using ROS-2 Humble Hawksbill LTS for a month now and want to contribute back to the community. I hope this is still open for contribution?
Also, if anyone else is also working on the same, feel free to connect.

Yes, please feel free to go through the open comments here and make PRs related to them. We can review the changes in the individual PRs.

[ssanket1010]

Is this open for contribution now ?

[clalancette]

Is this open for contribution now ?

Yes, but please keep in mind that this is 4 years old and things may have changed since then. So please review each bullet item, and open a separate PR for each of them (it will be easier to review that way).

[christophebedard]

For what it's worth, a PR was already opened for this issue: #5383.

[ssanket1010]

Hello,
If possible, I'd like to add one feature for the Ros2 documentation website for optimization.
such that page turning can be controlled by arrow keys, as it is annoying to scroll down on the page to go to the next page.

[fujitatomoya]

sounds good, i would recommend that we can create the dedicated issue for that new feature with pull request.