Recently we had a concerted push to update the ROS 1 how-to’s and tutorials for ROS 2. While this is certainly an improvement over the existing ROS 2 documentation we believe that ROS 2 presents a chance to dramatically improve the state of ROS documentation. As part of this concerted documentation and tutorial improvement process, we want to understand the needs of the different ROS communities.
Specifically, we want to develop a set of user personas that accurately represent the various constituencies within the ROS community. These personas should help us create better content, that addresses the community’s educational needs in a manner that meets the community where it is at. To build these personas we’ve put together a short survey that will help us segment the community. We’re asking everyone in the ROS community to take the survey and promote it widely in your network.
We plan to run the survey for the next six weeks (until 3/15/2020).
Please feel free to distribute the survey (retweet it, post it on forums, send out to your local list serves).
We will open source most of the data when we are done.
We will retain the free response / e-mail sections as confidential.
We would also like to hear your ideas about the future of ROS documentation.
What would help you?
What would you like to see?
What open source software communities do education and training well?
What itch do you need scratched?
What pedagogical mechanism have you seen be successful for teaching ROS?
Feel free to comment below. Remember that constructive criticism, specific examples (e.g. links, references, details) and data are generally more helpful than conjecture.
As a piece of input, survey is well structured and easy to fill in, very good job with that (probably opposed to some other effort such as ours in here , still open for contributions though!).
One bit I can suggest is to leave a text-box for users to indicate which robot they’re working on. IMHO I’d be interesting to reflect whatever conclusions taken on particular (hopefully open) platforms that can be used to document things better (e.g. document about security in ROS 2 using the Turtlebot 3).
As ROS 2 gets more and more adopted in proffessional use cases, I’d love to see documentation on:
The motivation for asking for a more generic “robot type” is that we’re trying to understand generally what individuals are interested in. Any documentation we produce will be for a more generic platform so it is not biased towards any vendor in particular. What we’re trying to understand is how much time we should devote to address the specific needs of UAVs, versus a mobile base, versus an N-axis arm, etc.
Here’s a question. Should we aim to replicate some of the course work that is out there in a free and open manner or should we instead focus on more definitive and structured treatment of a particular topic? I don’t think it is an either/or situation, but I am trying to understand which would be more useful.
It would be really cool if you guys did something where there are basic tutorials provided for a variety of stuff, but attached to them community tutorials/guides that are either more in-depth or for different use cases maybe?
This would certainly not be a case of either/or: different audiences will be interested in different things.
For our MOOC we (and my former colleague Mukunda had a big say in this) deliberately chose to create content around a particular scenario. Starting with the basics (pub/sub, services, pkgs, etc), gradually adding more, but always working towards the end goal, which is a specific use of ROS in a specific setting.
We did this because over the years we heard so many times that after the beginner’s tutorials “on the ROS wiki” newcomers felt as if they could not do anything yet. They experienced such a big gap between knowing how to create a publisher and subscriber – or how to create R2D2 with xacro – and creating an actual meaningful application that they felt lost.
If we could somehow address this with this new documentation effort that would be a very valuable outcome.
PS: personally I believe a good part of this is freedom-of-choice vs freedom-from-choice. There is so much software and there are so many different ways in which that software could be used to achieve certain goals that it can overwhelm newcomers (and more experienced users). Having “experience with ROS” seems to be as much about knowing what to use as to know how to use it.
Providing some guidance there could be beneficial in reducing the (perceived) learning curve. Perhaps a use-case or scenario-based approach could work, similar to what we did with the MOOC.
To that end, while the wiki tutorials feature wasn’t used much later in terms of adding more, I can say when I was learning ROS the tutorials for pluginlib and TF were critical to my ability to get even basic demos out the door.
ROS2 has enough “new stuff” that is pretty foreign to most robotics developers that didn’t focus on communications, I think some of those style of tutorials would be beneficial. Particularly when it comes to QoS (tutorials showing how it tangibly change results and how to deal with QoS conflicting types, and the somewhat tribal knowledge on the CLI implications of QoS), how to create action servers and clients, since without a SimpleActionServer, its pretty complex, TF2 in ROS2 changes, RVIZ2 changes for plugins, Gazebo plugins for ROS2 changes, ROS2 networking setup with multiple machines / routers (the ROS1 I frequently linked users to), lifecycle, multicast, Launch API (dear god does that need an extremely detailed line-by-line walk through), security (though amazingly straight forward, thanks everyone that worked on that!), … I could list another 10 things.
Hello folks,
I just did a quick answer on the survey and wanted to give a quick summary of my experiences with ROS2.
I am a student and the first time I got into contact with ROS was on some student job I had. This sparked interest and I always had it in the back of my head. Like three semesters ago I had to research and give a talk about the current state of ROS2, which was great. I really appreciated the new features of ROS and the new design in general. After I gave the presentation my professor asked me if ROS2 would be ready for educational purposes yet. I said from the functional point of view definitely yes, but it lacks the quality of the ROS1-Tutorials.
The reason he was asking was because in my Computer Engineering studies we have three RC-Cars with some jetson board on them which run ROS and are used for projects on autonomous driving. And when me and my buddy talked about DDS behind ROS2 he got super interested, because he wants those cars to interact with eachother and exchange data, which should be quite “easy” with ROS2.
Conclusion: We need more tutorials, examples and documentation. Especially the small ROS1 examples were always a HUGE help back when I started.
From my user point of view, what wasn’t always obvious to me was how do I search for existing packages for some specific use-case or category (be it motor control, inverse kinematics, or whatever you can think of). That would be my wish.
And so yeah, I am basically the one promoting ROS2 in my uni here and since the semester is over and I will have atleast a little bit of time over the next two months I think it would be cool if I could help out a little bit.
Any ideas how I could help out and where to start?
PS: Right now I am working on a simple 2wd robot with which i want to learn some more image recognition things, just in case that is interesting for which tasks i could possibly do.
One type of documentation which is not included in the survey, but which I find important is API references. In my opinion installation/running guide + conceptual overviews + API references are the most important pieces of documentation. Additional guides and tutorials are a nice bonus.
Maybe it is not included in the survey because it is considered trivial to just generate, but ideally the API reference will not just be a list of all the function names, but include complete descriptions of what the functions do(including in edge cases), how they can fail, and maybe even usage hints/references to related functions.
I would like to see more examples with real commentary as to what the code is expected to do and how it will behave. The examples at github.com/ros2/examples are a good starting point and trivial enough to understand without details assuming you’ve been at least dabbling with ROS 1. The code at github.com/ros2/demos purports to be more complete working examples but have zero documentation as to what to expect and why they are done as they are. In fact, my experience is the demos don’t all build right out of the box with Eloquent. A major problem is they require ros_testing and it seems to be missing and I can find no information on installing it. The github repository at github.com/ros2/ros_testing seems to really lacking. We’re rapidly approaching the 5th release of ROS2 and, to me, this seems a sorry state of affairs. Some groups either have special access to information based on some of the repositories I see on github or they spend an inordinate amount of time reading the ROS2 source which I’d rather not do. My aim is to develop code for my robot by leveraging ROS2 but the current state of affairs seems to require too much effort.
Totally agree with this part; we need more demos/examples with a lot more documentation on why they do the things they do.
Nobody has special access; this is an open-source project. And for what it is worth, building demos against Eloquent just works out-of-the-box for me. This isn’t the right forum for doing debugging, but we can debug what is going on with your setup in a GitHub issue.
I don’t know if the rationale was ever posted anywhere else, but this is what we talked about having years ago but haven’t been able to follow through with:
Tutorials
one good way to do things, lots of inline code comments with corresponding hosted tutorial that walks you through it
these are technical demonstrations, examples proving to ourselves and others that certain features are working or to give a preview to how they work before finished and documented properly
We’ve not had time to do the above, but hopefully this context will help people understand what we were trying to do. It’s not really clear to me what our long term plan will be with these repositories, now though. Maybe tutorials will be deleted, examples will continue being cookbook and tutorial material, and demos will live forever , I’m not sure.
, still open for contributions though!).
, I’m not sure.