We ran into an interesting issue recently with ROS 2 documentation that we wanted to discuss. Logging a bug against the docs didn’t feel like the right place.
We started students working in Dashing since it’s the LTS release and because they were working with hardware that’s only supported up to Dashing. However, they were unable to complete beginner tutorials like ROS 2 Topics and ROS 2 Services. There were a number of commands (e.g. ros2 interface) that failed in Dashing since they were introduced with Eloquent. It ended up being a somewhat off-putting first exposure to ROS.
We’ve all seen the data that shows that more users use the LTS than just the latest release; we see the same trend in Ubuntu, and it shouldn’t be surprising to any of us. Therefore, the first point we want to discuss is if it would be worthwhile to, at least in the short term, keep the documentation reflecting the LTS (where most users are) as opposed to just whatever the latest release happens to be.
The second point we want to discuss is the long-term path toward having documentation specific to each release instead of just one. For example, we appreciated how each ROS 1 tutorial had the ability to switch between releases and build tools (if necessary). Is the plan for the ROS 2 documentation to go that direction? Or, since it’s all in git, is the plan to maintain a separate branch of documentation for each release and expose them separately on the index?
Atm the documentation of different distributions needs to be handled on the content-level:
either create separate pages for different distros
or annotate the content on a page to be specific to certain distros, available as of, etc.
The current infrastructure doesn’t offer a way to utilize separate branches and updating the part of index.ros.org to do so would be “challenging” to say the least.
So to answer the first part: those pages should be updated to clearly annotate which features are only available in newer distros.
The topic what features regarding documentation we would like to have has been discussed many times in the past and has several aspects (central hosting for searchability, review / approval process for changes, support generic as well as distro-specific content, distinguish platform specific docs, support package-specific documentation, incremental generation for scallability, etc.). Any previous attempt to improve ROS 2 documentation has taken a shortcut due to resource constraints and as such each incremental solution had (and has) significant limitations.
So to answer the second part: we need to find the necessary resources to implement a solution which covers all these cases. It would be great if that can happen between Foxy and G-turtle - but we have said the same after Dashing a year ago…
@kyrofa I actually came across this exact same error two days ago as I was working on a new tutorial for Dashing. I know it is an un-satisfying answer but I was going to drop a note in the docs just as soon as I wrapped up the task at hand.
More to the point I am in favor of keeping the primary documentation pinned to the latest LTS. At minimum I think we need to tag documentation when it hits a release goal. I don’t see why we couldn’t generate a static copy of the docs from the tagged release and have them hosted somewhere. That may not be the best solution but it is better than nothing.
I definitely understand the frustration with having commands in the tutorials that aren’t available in the last LTS. That’s something we have to fix (see below for some thoughts on that). However, I have to agree with @dirk-thomas that it’s not really reasonable to constrain documentation this way. We definitely have users who are using the latest, and we want them to have documentation for the latest features as well. In the short-term, I think the best we can do is add some disclaimers on what versions some of the commands are available in. I believe we have done this in some places already (@maryabelanger can correct me if I’m wrong), so maybe we should expand that practice.
I’d really like to see us get to a place where we can switch between releases much like the ROS 1 wiki or readthedocs.io pages. I think it makes most sense to have separate branches per-release (as that is just a natural way to do it), but I’m not picky about the mechanism.
The long term plan is to version the content in ros2_documentation (tutorials, installation pages, troubleshooting, concepts, etc.). We’re trying out different solutions for that right now (that shouldn’t affect infrastructure too much ), and it’s a priority.
The short term solution that’s being utilized in the tutorials and some other docs right now is annotation using tabs, like here and here. This can be done for code syntax or even just descriptions or explanations that apply to one distro and not another, like here. We also use tabs for annotating OSs, CMake/Python, and C++/Python
When you find something in the code that works for one active distro but not another, please open an issue or PR pointing it out so we can add a tab for that distro. Completely replacing Dashing’s syntax with ros2 interface instead of tabbing it was definitely a mistake!
That’s fair. If our current infrastructure doesn’t allow us to have documentation branches, I agree-- I’m in no way advocating for not documenting new features. I really just wanted to mention that most folks reading these docs will be using the LTS, which is perhaps a mismatch with the current approach/priorities on the docs as judged by notices like this (taken from the tutorial index):
Just because we can’t branch our docs right now doesn’t mean we need to give up on making the docs useful for earlier releases (particularly the latest LTS), right?
Thank you @maryabelanger, that is a great short-term solution, and is not something that I knew we were capable of doing.
I’m pleased to hear that! I know it’ll take a while, of course.
While we’re going through that process, let me revisit my LTS point. Given the ability to make tabs within the documentation as @maryabelanger just pointed out, I think we can make this work, but we need to all approach the documentation with the right mindset, that is: “most of my readers will be using the latest LTS.” Again, I’m not advocating against documenting features only available in newer releases. I’m advocating against having the “these docs are only applicable to Eloquent” notice, against not having tabs to make the documentation applicable to both, and for making sure the docs are tested against the latest LTS as the primary documentation target. Does that seem reasonable?
Totally! Does that mean that we can remove the notice mentioned above, then? It makes this situation seem intentional, otherwise we probably would have logged a bug.
Does that mean that we can remove the notice mentioned above, then? It makes this situation seem intentional, otherwise we probably would have logged a bug.
Yup! We’ll remove it soon since we’re updating everything for Foxy right now. It’d be ideal to remove the disclaimer completely, not only for Eloquent but the “only Linux/Debians” part as well (more tabs). But the only really efficient way to patch the holes for Dashing now is just reporting it if you come across one, because we can’t really dedicate time to Dashing testing. If I recognize any off the top of my head while Foxy testing I’ll make sure to add them in.
), and it’s a priority.