ROS 2 tutorials upgrade & entrance level complexity

General
1

Hi, this will be a long post!

I’m a late ROS 1 → 2 transitioner with a research and teaching background. I learned ROS long ago by myself and was also taught it at under and grad level. However, when I arrived at ROS 2, I had a hard time adapting, even though I had plenty of experience with ROS. After a year, I have thought deeply about the reasons and arrived at two main reasons:

  1. The tutorials and onboarding experience.
  2. There is a lack of established practices.

The second is getting better every day, and I think that it’s a matter of convergence for the community. However, the first is more concerning, in my opinion. Over the last months, I have gathered a series of points that could be improved and I would like to share it with all of you, get your feedback, and possibly your help for improving the tutorials and general docs. The aim of this post is to work towards a general tutorial upgrade to ease the entry-level experience for users.

Why? ROS tutorials are the entry point for both newcomers and transitioners. From our teaching experience, if the complexity gets overwhelming, students will simply avoid ROS at all costs. I have discussed this issue with people from different backgrounds and experiences and agree that, currently, it’s difficult to approach ROS 2 unless you have been an early developer.

Why now? ROS (1) EOL has arrived, and a lot of transitioners will use the tutorials to look for differences between the two major versions. Any undergraduate and graduate education that didn’t transition will do it before the next semester starts.

How? So far, I have gathered in this document (EDIT: Please, even if you leave a comment in the GDocs, write also a comment on this post to keep it alive) a list of improvement points with a clear action that could be turned into a GitHub issue in the docs repo. However, before flooding the repo, I would like to have some initial feedback from the community, hence this post. I think that some organization such as a work group could also be interesting.

Next steps So far, I would appreciate some feedback on the general idea and the specific ideas in the document linked above (it has commenter permissions). I would also appreciate any other ideas in this post. Finally, ideas on how to organize the workload and a possible work group are also appreciated. After that, we could move on to the actual work!

Just as a disclaimer, this post is not a complaint. I understand that the whole community puts a lot of effort into gradually improving all the content. My objective is to give it a push so everyone can have an easy approach to using and contributing to this community.

12 Likes
2

this is a necessary and critical ROS topic. (pun intended). As a newbie learning ROS2 Jazzy (2 months in), and still not having built a real robot, I resonate with many of these points. One thing I will add is it needs to be made more clear what development environment is best for getting started with ROS. In short, after experimenting with getting ROS working on MACOS, Windows, WSL2, and a dedicated Ubuntu machine, it’s abundantly clear that a dedicated Ubuntu setup is best for a beginner wanting to learn ROS end to end (software to real robot hardware). And not on a raspberry PI as many youtube tutorials would suggest, but a decent laptop or PC that can serve as the “master” node.

3 Likes
3

Thanks, @davidmc, for all the effort you put into this. Many of the topics you mentioned were a real challenge for me while studying ROS/ROS 2.

I once saw a post that proposed creating a pyramid of challenges to provide the ROS community with a structured set of guidelines to ease entry into this world and reduce the steep learning curve we all face at the beginning. It could be interesting to revisit this idea and consider it in relation to the key points you raised to make ROS more beginner-friendly.

Additionally, I believe there is a huge difference between “complete” newcomers and those with a developer background. However, I still wonder whether ROS is truly accessible for the former, as, in practice, you don’t usually start by creating nodes but rather by importing launch files and using code from others—often skipping the fundamental step of learning the code itself.

2 Likes
4

Thanks! I think the pyramid idea of challenges is great. I also think that this pyramid shouldn’t be proposed by experts but actually by newcomers. Otherwise we might bias it based on our believes.

1 Like
5

Thanks! You concern was addressed precisely on the PMC meeting related to the ROS Docsite rebrand by Katherine Scott.

Personally, I believe Jazzy on the correct Ubuntu is the only entry-level option. Some very basic things are missing from Humble, which is already 3 years old, such as running Gazebo in a friendly way from ROS (gz_ros launchfiles), and the Python launch system is under active development. If students need it, they can Dockerize the system, which works flawlessly for me on Ubuntu 20.04 and mostly okay on Windows.

A side effect I intend with this work package is to also establish a “tutorial deprecation notice” system as included in the last part of the GDocs.

1 Like
6

I agree with a lot of the points in the document.
Each new ros distribution seems to deprecate features fast and introduce new ones, so it is hard to keep up when learning. And it is a pain in the rear that new ROS2 versions are tied to the newest linux releases. We work with a lot of hardware that in an industry is very slow to release new drivers - if ever. This means I have to use Docker left and right, and ROS/DDS does NOT play nice with inter-distribution communication.

1 Like
7

Totally agree about that as well. Still, I did find that example really interesting and user-friendly, at least the first floors of it. In case you wish to read about it, here’s the link Ideas for a ROS skill tree

1 Like
8

Thank you for starting this discussion! Personally, as a student, I’ve found both ROS 1 and ROS 2 overwhelming, making it difficult to grasp core concepts. To simplify things, I often resort to generating code with GPT or piecing together components from pre-written examples. This could be a game-changer in helping me properly learn ROS-2 for a healthier career.

One major gap I’ve noticed is the lack of structured, easy-to-follow video tutorials. While guides are helpful, video content often makes it easier to grasp concepts that might be missed in text. Unfortunately, most existing tutorials require heavy setup and aren’t beginner-friendly, making it tough to prepare and program robots efficiently. A well-structured video series with minimal setup and hands-on examples would make ROS 2 much more accessible for students and transitioners.

Really excited to see how this initiative shapes up, and I’d love to contribute in any way I can!

1 Like
9

With respect to “operating systems recommended for new users” we’re still discussing this! I will probably try to put together some changes later this week. We have a lot of opinions here that we have to balance out, but realistically students should only be using the latest LTS with a Tier 1 OS.

First I want to point out that you are more than welcome to file tickets on the docs repository. I can point a contributor at a ticket, a Google doc not so much.

The thing I really really really want people to keep in mind here is that the core team of regular contributors is very very small and we spend the overwhelming majority of time working on the docs. I was talking to the board of the other non-profit I work with, The Open Source Hardware Association, and there seems to be this mistaken belief that all non-profit entities have a large staff. This is not the case! OSRA / OSRF has two full time people. Here at Intrinsic there are a handful of us that regularly contribute to the project, and most of these people have other work obligations. There are a few other regular contributors scattered across the community, like @christophebedard and @tomoyafujita, that do a ton of work. All of this is to say, we need your help!

This list is helpful, but what would be really helpful for us is more regular contributions from the community. If you see something that you think needs improvement there is nothing stopping you from doing so. If you think that,

“Custom ROS2 interfaces: The reference about having to add rosidl_get_typesupport_target(cpp_typesupport_target ${PROJECT_NAME} “rosidl_typesupport_cpp”) in order to allow message generation in the same package is not clear or explained. Both tutorials, “Creating custom …” and “Implementing custom…” could be merged or more clearly separated.”

then we need you to at minimum file a ticket. Alternatively you can just send us a pull request to make the change! There are no gate keepers here (other than reviewers). Everyone who uses ROS should feel empowered and encouraged to make changes, even those who are just learning about ROS. There are often discussions about organizing efforts to make things happen, and we can certainly do that, but what I’ve always found helpful is to take the time to make the tools I use every day better. For example, the best time to the file a ticket about the custom interfaces tutorial is after reading the tutorial.

Finally, I want to remind everyone that the OSRA / OSRF are the organizations that help us keep our project infrastructure running! People really should join the OSRA. More importantly, every ROS user should speak with their university / employer about supporting the OSRA / OSRF.

10 Likes
10

Thank you for your comments and taking the time to review the GDoc.

Also thanks for the we need your help message! That’s exactly my objective with this post, to gather and organize people to fill in those tickets in a manageable way. That will be on the next steps, as @christophebedard advised me in an email exchange.

Firstly, I wanted to validate that my point resonates with the community, as tutorials are created by and for the (current and future) community. Ideally, these ideas should receive feedback from very experienced ROS developers, educators and new test users.

Once this post, the GDocs, and any other potential source of ideas are collected, and turned into clear actionable proposals, they will be added as tickets.

Finally, having yours and any other PMC and Comitters supervision and help in managing this at any possible extent would be great.

2 Likes
11

I agree with planning and wanting to be sure you’re doing the right thing before you do it, but I want to emphasise that just diving in and proposing a change with a PR is the absolute best way to get feedback on that change and ensure it turns into the best solution to the problem it’s trying to resolve. Having put together a Google Doc of things you see as problems is a great start, but you should now just dive right in and start changing things. Don’t wait for “enough information” or “enough feedback”. After all, there’s no reason we can’t modify something that was changed again in the future.

4 Likes
12

I hope we get there soon! Thanks for the recommendation. I expect to move forward in the following weeks with anyone who would like to join.

1 Like
13

Well, prior to @Katherine_Scott 's post, I was going to mention we need more MicroROS tutorials. but the key is this " Everyone who uses ROS should feel empowered and encouraged to make changes, even those who are just learning about ROS

Challenge accepted, i’ll file a ticket for a additional MicroROS tutorial and open a PR for the tutorial. Total noob here, but the experts can chime in and improve on it before approval. I guess Continuous integration doesn’t just work for code, it works for docs.

2 Likes
14

I think that Google Doc is really good, I was expecting a list of “whinges” (which some may think it is) but I think most of those are really valid points.

Something I think is quite important is what @Katherine_Scott raised in the comments - who is the target audience? That particular comment was around the Composition page and whether the ambiguity of libraries vs executables being preferred is confusing, personally I think it could be a little better but also you’re in the “Intermediate Concepts” section so also you can expect it to be more nuanced. But I think the approach that “some users are migrating from ROS 1” can sometimes be very alienating for new users, even if it does cover a huge audience.

For example if I am wanting to learn about composition and I approach that page, the opening paragraph is about how things work in ROS 1, with a link to the old wiki. One may think the intended path to learn about composition is to first go to the wiki and learn how it works in ROS 1, and then you’ll be ready to come back and learn about ROS 2.

Does that help experienced ROS 1 users to migrate? Probably. But it absolutely does so at the cost of the “new user” experience and adds to the negative attitude some have towards ROS 2. Personally I think it’s unhelpful in the long-term for a project’s primary documentation of key concepts to be written with an older version as expected context, but I get that in this case that probably includes a lot of people.

To be fair I actually think most of the docs have come a really long way in the last few years and are a pretty good on-ramp for a beginner. This is really just one bad example, and I understand that at the end of the day it’s up to the community to come up with something better, I just thought that was an interesting point that ultimately affects the whole approach to documentation.

2 Likes
15

I’m also a student who initially had a lot of trouble with ros 2 (and gazebo), despite significant programming and robotics background. I’m going to disagree with what a lot of people here have been saying about tutorials and documentation – most of the current documentation and tutorials are somewhat decent for getting specific pieces of information. While more tutorials would be good, it wouldn’t significantly improve/flatten the learning curve.

What would really help is a curated set of fleshed out example projects that demonstrate exactly how things are done according to best practices. For example, a full (including everything, launch files, urdfs, etc) example for an ackermann drive with gazebo simulation and ros2_control integration, would do wonders. In general, people might find it easier to learn from reading through a working codebase than piecing together sparse documentation.

8 Likes
16

I realized yesterday (I get to use the word ‘flabbergasted’ now) that ROS2 distribution are not backwards compatible with packages made for previous releases.

For example GitHub - ros-perception/image_pipeline: An image processing pipeline for ROS. for Galaxy needs to be modified for Humble. This just hurts the adoption of new releases in my opinion, because not many developers have the resources to keep updating their packages.

I don’t know if it is because of how ROS ties into the Linux kernel. Coming from the world of Python, a package made for Python 3.6 is still (largely) usable in 3.7 - 3.8 - 3.9…

17

Thanks for your comments and I’m glad that I “surpased” your expectations :face_with_tongue: I think whinges only serve one self with a strong opinion. I don’t want to fall into the “this should work differently” type of comment, nor do I want to reinvent the wheel. As other comments say, the tutorials are good, but if this post resonated with a fair amount of people, something can be done to improve.

I completely agree with your composition example. I think ROS 2 tutorials are a mix of (disclaimer: this is just my feeling):

  1. What was done for ROS 1 tutorials, which worked.
  2. Explanations to ROS 1 users on how things have changed in ROS 2 offering background, which is useful for them.
  3. Some continuous integration features along ROS 2 development that want to be established as standard practices. ROS Foxy or even Humble tutorials are quite different from Jazzy in this sense.

I think these three types of intention sometimes mix and might create confusion among users with different backgrounds. @Katherine_Scott comment is really important in this sense and I think it’s a challenge to balance the approach in the tutorial. My proposal in that sense would be:

  1. Try to follow and possibly improve what is already there based on fresh users feedback.
  2. Possibly create and refine the path for ROS 1 newcomers. There are specific sections around Docs for this but maybe they could be put together as tutorials.
  3. Try to homogenize established practices. I know this is something that will necessarily change over time, and that’s precisely why it should be periodically revised.
1 Like
18

I really like this idea and it could be used to distill best practices that people would replicate and use as a reference.

2 Likes
19

Yes THERE IS A REASON! Version whiplash and the fact that deprecated / non-working 3rd party tutorials and videos live forever in search engine results.

ROS 2 is a community project, and the community needs to apply our efforts efficiently. I rather doubt the steering committee wants to have to review thousands of PRs that solve a thousand particular user’s issue, to ensure a few general good ideas get incorporated into ROS 2.

I understand the OP’s thoughtful approach of discuss, triage, then offer suggestions for areas most needing change.

2 Likes
20

I think you nailed it. Learn by looking at good curated examples of projects that work end-to-end is the best way to learn the architecture of the system and its the fastest way to start building stuff.

2 Likes