ros2_documentation icon indicating copy to clipboard operation
ros2_documentation copied to clipboard

Published 20 hours ago • verified publisher icon ros2

ROS 2 documentation suggestions

Open mjeronimo opened this issue 3 years ago • 10 comments

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.

mjeronimo avatar May 10 '21 21:05 mjeronimo

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

Aut0R3V avatar Sep 05 '21 20:09 Aut0R3V

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

audrow avatar Sep 07 '21 21:09 audrow

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

pr-db avatar Oct 12 '21 05:10 pr-db

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.

clalancette avatar Oct 12 '21 12:10 clalancette

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.

songyuc avatar Aug 16 '23 07:08 songyuc

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

clalancette avatar Aug 21 '23 12:08 clalancette

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

songyuc avatar Aug 21 '23 13:08 songyuc

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!

clalancette avatar Aug 21 '23 13:08 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.

prateekbhaisora avatar Dec 19 '23 15:12 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.

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.

clalancette avatar Dec 20 '23 20:12 clalancette