ROS 2 documentation suggestions

mjeronimo commented 3 years ago

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 commented 3 years ago

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

audrow commented 3 years ago

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

pr-db commented 3 years ago

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

clalancette commented 3 years ago

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 commented 1 year ago

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 commented 1 year ago

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

songyuc commented 1 year ago

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

clalancette commented 1 year ago

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 commented 11 months ago

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 commented 11 months ago

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.

ros2 / ros2_documentation