ROS 2 tutorials upgrade & entrance level complexity

We’re talking about documentation here, small incremental changes are better for everyone. They don’t cause “version whiplash”.

Please don’t speak for others.

With the experience of years of contributions, 1000 small incremental improvements would be great, and are going to be easier to review and merge for the maintainers than a single change that tries to include all 1000 changes at once. Different issues will touch different parts and synchronizing all 1000 changes at once is a much bigger challenge when you couple the review of all the components. If any of the 1000 changes needs to be revised on review all of the other 999 will have to wait while that gets hashed out. And if you have several different changes in different areas being reviewed by different people on different timelines/timezones you can gradually get to a point that getting it satisfied for everyone simultaneously will take an extremely long time and if there are related changes happening too it may have to be refactored regularly. All of the 1000 changes are good ideas, not just a few of them.

6 Likes

Right, good point.

Point taken.

Emotion speaking now: This just seems like a rerun - many times NOOBs come in eager to help, but they are too inexperienced to help. If they ask questions on StackExchange, they come away feeling they are not worthy there. If they solve their own problems and teach them self enough to have some success, they come dip their toes into the “discourse” about ROS, and come away feeling their ideas for discussion should have been neatly packaged and presented somewhere else (issue or issue with proposed solution). Sure neatly packaged ideas and even more so implemented ideas are the most beneficial, but sometimes it seems the only safe space to discuss ROS is on Reddit.

Sorry, that’s my “entrance level complexity” experience.

1 Like

Let me preface this by saying I think people expect a lot from us and then get frustrated when we don’t live up to their expectations. Some people expect ROS to be one small step up from a kit they buy at a toy store. The reality is that professional robotics and robotics research is hard and hard things are often hard to learn. Our job is to try and make it EASIER. Making robotics EASY would require that we sandbox all of our users to just one or two narrowly scoped domains.


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.

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.

You are aware that we have multiple reference platforms for the project right? Unfortunately we can’t cover all the possible permutations out there (flying robots, wheeled robots, legged robots, tracked robots, etc, etc).


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.

I am going to be up front here and say this won’t happen any time soon. Videos are not searchable. You can’t copy / search the code. They are a HUGE lift in terms of production time and resources and we would have to redo all of them every time we make a release. Don’t take this the wrong way, but a lot of us learned ROS through reading and it is still an important skill for professional software engineers.


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.

I think it is great that people are producing videos, but I really wish more of them would send us a docs pull request instead. Unfortunately you don’t get any “influencer clout" from sending our documentation a PR. We also seem to be held accountable every time someone on the internet says something that is factually untrue, misleading, or omits details.


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

This seems like an assumption on your part. You can’t mix C++ 17 and C++ 11 or Python 2 and 3 code together, similarly you can’t use two different releases of a database system without a migration. Why would you assume you can use two different ROS releases in the same project? It is certainly something that could be possible, but it is a really really heavy lift, and the project is slowly moving in that direction. Distribution changes are the time when it is possible to break compatibility, and we don’t guarantee that things are compatible to give maintainers an opportunity to make changes. Any individual package will depend on their own changes and those of their dependencies. We do hold core packages to a tick-tock cycle to not have changes be too fast.

4 Likes

I would hope this isn’t directed at me.

Apparently not. I encountered the turtlebot and turtlebot2_demo repositories while trying to learn ros initially, and got the impression that the platform was unmaintained. It’s nice that the project does exist as a reference, and I will likely use/recommend it in the future as a resource for getting familiar with ros codebases. Perhaps it might be a good idea to link to the turtlebot4 repository as a resource somewhere on docs.ros.org?

@davidmc

thank you very much for creating doc enhancement proposals. this is good start to get some feedbacks and attention, that you already got :smile:

we can of course keep the general discussion in here but i highly recommend you to create the issue to GitHub - ros2/ros2_documentation: ROS 2 docs repository for each proposal, so that we can discuss on more details and specifics as dedicated issue to track.
IMO, important thing is progress, not perfection at a time, probably we can take these issues step by step together, and then it will be something close to perfect thing? :thinking:

i am happy to support this, please let me know if anything’s up.

thanks,
Tomoya

4 Likes

@tomoyafujita
Thanks for your support! I completely agree and will do it soon. This discussion is definitely shaping my understanding of how the proposals should be dealt with (lots of feedback!)

You are aware that we have multiple reference platforms for the project right? Unfortunately we can’t cover all the possible permutations out there (flying robots, wheeled robots, legged robots, tracked robots, etc, etc).

Would more be a problem? Something I believe @AngleSideAngle refers to and which is currently missing are “simpler” or “toy” complete examples for beginners. The examples you linked already start with cloning repositories, which include lots of functionalities. A good example that I found useful and valuable while learning ROS was: GitHub - leggedrobotics/ros_best_practices: Best practices, conventions, and tricks for ROS. Does anyone have any thoughts on this?

I am going to be up front here and say this won’t happen any time soon. Videos are not searchable. You can’t copy / search the code. They are a HUGE lift in terms of production time and resources and we would have to redo all of them every time we make a release. Don’t take this the wrong way, but a lot of us learned ROS through reading and it is still an important skill for professional software engineers.

Again, is there any problem on suggesting it as an idea? I don’t think people in this discussion are demanding anything. We are throwing ideas off to the community and it seems that there is a clear missunderstanding as if we are complaining or asking anything from OSRF / OSRA. Regardless, I agree that videos are really difficult to maintain and can get old very fast. However, if people resort to videos is probably a sign that Tutorials could improve :slight_smile:

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

This is definitely not related to Docs. Even though I like the conversations being held here, I think it would be more useful to focus on specific improvement proposals related to the Tutorials & entrance level complexity

3 Likes

Would more be a problem? Something I believe @AngleSideAngle refers to and which is currently missing are “simpler” or “toy” complete examples for beginners.

So, like TurtleSim?

The examples you linked already start with cloning repositories, which include lots of functionalities. A good example that I found useful and valuable while learning ROS was: GitHub - leggedrobotics/ros_best_practices: Best practices, conventions, and tricks for ROS. Does anyone have any thoughts on this?

My thoughts here are that it would have been really awesome if the author of that repository contributed it to this Github organization, went through the process of making it a repo template, wrote documentation about it here, and then followed up maintaining and updating it least once or twice a year.

Speaking of maintenance, it isn’t good enough to just write new documentation, we also need people to maintain and update the documentation we already have. We generally do this during the T&T party a few weeks before the release. That should kick off around May 1st of this year.

1 Like

To clarify, I was suggesting more complex example projects that are close to real world applications, not simpler ones. The turtlebot4 repo is a good start, and I definitely wish myself from one year in the past knew to reference it.

Some other things I believe would be beneficial to have example projects for are (new) gazebo simulation/ros integration, ros2_control, and microros. All of these I have found to have relatively sparse (if not misleading/outdated) documentation or examples.

I understand that you are frustrated by consistent, and often unhelpful, discussion on ros2 tutorials/documentation efforts. I am merely offering an idea to a thread asking for suggestions on how to improve ros2 documentation to make it easier to learn/use.

Exactly! As I told @davidmc in our email exchange, many of the suggestions in the GDoc are pretty straightforward and could be turned into issues – or even PRs directly!

For some of the other comments, e.g., “why this way and not that way,” there is often an explanation for the current state. It often comes down to having to consider multiple use-cases or different kinds of users, but an additional perspective is always useful, and yeah we can discuss each comment separately under issues in the ros2/ros2_documentation repository.

:100:

If there’s something I learned about documentation, it’s that it is crafted, PR by PR, and not simply written. Great documentation doesn’t just appear overnight :smiley:

4 Likes

What do you all think about starting a weekly ROS2 livestream?. Perhaps have different guests on each week discussing certain topics. Long-form live conversational discourse between real people discussing challenges/learnings/resources can be a powerful tool

Great idea. However, considering the current number of issues and PRs, it might be challenging to find someone with enough time to guide this

Although I’m generally not a very big fan of LLMs, I think they could be helpful here. Searching through videos using text? Youtube already has it…

Now imagine you’d be able to write a tutorial, add a few script annotations (as in movie script) and let an LLM generate a video tutorial. Updates would be easy.

Why should anyone do such a thing? Well, I’m myself also rather a text reading person, but looking around me, even my brother of the same age uses youtube instead of googling thing. So yes, there are people who have a need to search for video answers to their questions…

2 Likes

Nice topic, and I agree with many of the points of the doc. I also understand the POV of @Katherine_Scott, and in my little experience it feels like ROS is a huge codebase continuously evolving. If it lacks manpower, it’s understandable to prioritize solving issues and introducing new features over maintaining an updated documentation (also considering that the same documentation may be outdated a few months later).

I agree with that too.

I started using ROS to create a pick and place application with a 6 axis cobot. Possibly one of the most basic industrial applications I can think of.
When I started with ROS (less than 6 months ago) I thought I could find an almost usable solution to my relatively “simple” problem, and deploy it quite quickly.
Instead, I found many different interesting “components” that I couldn’t figure how to configure or combine to obtain a functioning solution.

After a while, the only way to try and obtain something usable in a decent amount of time was to stick to the basics and build from that for my needs.

Even after building something that is more or less beginning to work (ManyMove), I’m not sure how much I can contribute to the documentation, as the reason I started writing a repo myself was that I couldn’t deeply understand how the available ones worked in a practical way.

As soon as I can finish up some basic features I want to create at least some tutorials. Then I’ll try and see if there is somewhere I can help with in ROS documentation.I understand very well the struggle in documenting the code, in ManyMove itself I tried to keep some useful comments updated and to build some documentation, but getting it to work comes obviously first.

3 Likes

I want to highlight that a video tutorial from documentation could be a simpler process and as recommended by @peci1 using LLMs could further automate the process.

Why I personally prefer videos over text is because video tutorials offer learners a clear visualisation of expected outcomes. This visual assurance is invaluable in minimising errors during setup and development, as well as this helps the inexperienced programmers gain confidence in learning ROS.

In fact, it is present

I must admit that it is very easy to mislead and don’t see it due to the many information available, but Turtlebot has been always the goto platform to start learning ROS (at least it was in my case) because of all the examples available.

1 Like

I couldn’t agree more with this point. Working with a large codebase - even just the ROS2 core packages - on your own is inherently challenging. And that’s before even getting into the broader set of skills needed to really understand robotics problems.

ROS gives the impression that building a robot is straightforward, but that’s only true if you already have a solid foundation in areas like C++/Python, build systems like CMake, Linux, networking, and robotics principles. Many people struggle with ROS not because the system itself is overly complicated, but because they’re missing pieces of that foundational knowledge.

There is a learning curve—but once you have that background, picking up ROS isn’t all that different from learning any other framework or middleware. Better documentation can certainly help, but it’s not a silver bullet. Gaining the necessary experience just takes time.

That said, I’m definitely not criticizing anyone for not knowing everything up front—we’ve all been there. The good news is that learning resources have improved dramatically. With tools like ChatGPT and all the great content on YouTube, it’s honestly way easier to get started today than it was even 5 or 10 years ago.

5 Likes

So, like TurtleSim?

Yes. I think TurtleSim is a great example and maybe it could be used to incorporate other tutorials or concepts around it. As I said previously, not necessarily modifying but extending.

My thoughts here are that it would have been really awesome if the author of that repository contributed it to this Github organization, went through the process of making it a repo template, wrote documentation about it here, and then followed up maintaining and updating it least once or twice a year.

Good guidance. I guess this can be also turned into an issue listing those steps for someone to step in.

Speaking of maintenance, it isn’t good enough to just write new documentation, we also need people to maintain and update the documentation we already have. We generally do this during the T&T party a few weeks before the release. That should kick off around May 1st of this year.

Agree. I also agree on the fact that it would be ideal to have a full time person working on Docs. Since that’s not the case, trying to gather the most people from the community and raise awareness of this issue seems the way to go for me.

ROS gives the impression that building a robot is straightforward, but that’s only true if you already have a solid foundation in areas like C++/Python, build systems like CMake, Linux, networking, and robotics principles. Many people struggle with ROS not because the system itself is overly complicated, but because they’re missing pieces of that foundational knowledge.

I agree a lot on this. However, I was able to work with ROS (1) for a long time without any deep understanding about CMake, Linux, or networking. I din’t even know the effect of source, or how CMakeLists really worked. I learnt those things after a while. And I have seen this is the case for other people around me. However, that was not the case for ROS 2. I had to learn many new concepts before I could work out something basic.

It is on my list to implement some sort of ROS “Office Hours”, though with the upcoming Kilted freeze it has not been my highest priority.

I will make some time to actually plan out what this should look like and what a good schedule would look like that is accessible across multiple time zones.

Thanks for the push!

3 Likes