search

ros2 / ros2_documentation

ROS 2 docs repository
https://docs.ros.org/en/rolling
Creative Commons Attribution 4.0 International
532 stars 1.05k forks source link

Proposal for reshaping Launch tutorials #4453

Open knmcguire opened 4 months ago

knmcguire commented 4 months ago

During the Jazzy tutorial party I've dived into the Launch tutorial series. Even though I've followed these multiple times, I still find myself having difficulties following them, especially the substitution and the big project handling one. See those two issues here:

I was right in the middle of rewriting these separately when I came to the conclusion that this will be a bit of a bigger project and that I'll need to coordinate with y'all if you'd agree with my proposal. The problem with the Launch tutorial series is that there is quite some overlap between the separate tutorials, and that complex concepts were introduced too soon (in case of the substitution tutorial), or that too many classes and concepts were all in one big tutorial, which made me lose oversight very quickly. This is probably due to legacy tutorials being appended by new functionalities perhaps?

Proposal

Since I liked the event handler tutorial due to it's limited scope (see this ticket) it actually inspired me a bit for a possible improvement proposal:

  1. 'Working with launch files': This will be a combination of 'Creating a Launch file and Integrating launch files into ROS 2 packages. This basically introduces the LaunchDescription
  2. 'Basic Launch actions': This goes through some commonly used launch actions DeclareLaunchArgument, ExecuteProcess, TimerAction. Basically this part of the substitution tutorial but not continuing with any of the substitution examples.
  3. 'Conditional launch files': This perhaps might need to be written from scratch, but with the knowledge that the user now knows from the previous tutorial, to write an example that adds a if condition run on a launch file based on a launch argument (which they learned before)
  4. 'Launch file with substitutions': Perhaps with the previous tutorials added, the original substitution tutorial might be better to follow, but I would still recommend a more concentrated tutorial substitution alone, and leave the main launch file out
  5. 'Launch file Event handlers': I propose just reusing the event handler tutorial, but depended on what will be handled before.
  6. 'Managing Large Projects': Here we will focus on the IncludeLaunchDescriptions, Yamlfile, remapping, etc. Technically the original tutorial will do (although I'd leave the EnviromentalVariable for another tutorial perhaps).

I am not proposing a full rewrite, but I do think that some reshuffling of some existing content already and rewriting to improve the flow, will already make things way better. Also, we can also choose to not show everything either, but just most used ones and refer to the developer documentation in case the reader wants to learn what else is possible.

Let me know if you have any thoughts or if you agree with my proposal?

knmcguire commented 4 months ago

I also figured that I could also pose this question on discourse as well, such that more people can get their input on this

clalancette commented 4 months ago

So, in short, I totally agree with you that we need to revamp the Launch tutorials. I actually had a long conversation about this with @hidmic over at https://github.com/ros2/ros2_documentation/pull/3950 .

That said, your project seems much more manageable. So I think that it is worthwhile to pursue what you outline above, at least as some improvement to the current situation.

knmcguire commented 4 months ago

Ah oke! I searched on issues if there was any open about the launch documentation but I didn't search in PRs so thanks for letting me know. A quick look it seems that it's just about the user-guides and the concept documentation, so it's not like we are cutting each-others fingers if we merge both.

But now that I know that this is considered a good idea I'll get started on it! Once I got a draft, perhaps I can use discourse to get some testers on this new documentation as it is a big project and I'm sure mistakes will be maken.

knmcguire commented 4 months ago

Also another improvement we can make: TF2 tutorials should happen before the launch tutorials. This was probably done to explain the launch examples of TF2, but currently, the launch tutorials contain way more transform broadcast examples which the users are experiencing at the first time. Perhaps to help with this, we can make write a very simple 'beginner launch tutorial' for the beginner tutorials to get people acquainted with the concept more earlier on