I’ve noticed that when I search for ROS 2 documentation on Google, the results often point to the Foxy distro documentation by default, even though Foxy has been EOL for a while now. This means I have to manually switch it to a newer distribution, such as Humble, every time.
Given that Foxy is no longer supported, it would be really helpful if the default ROS 2 documentation on Google could be updated to point to the latest active distro (like Humble or later). This small change would save a lot of time and reduce confusion for those seeking up-to-date information. While this would be a very minor change, I think it would help newcomers find the documentation they are looking for more easily.
Has anyone else noticed this? Could this be something we can adjust for the future?
Looking forward to anything that improves documentation.
That said, I often prefer looking at the Foxy documentation for rclcpp. I find the new Sphinx-style documentation to be unreadable for C++ projects; I much prefer the old Doxygen-style documentation.
It does seem like some expertise (perhaps a contractor) with SEO, Sphinx, and RTD versioning background is needed to address this. I also feel like searching for ROS how to (installing / configuring DDS / how xyz works, etc), the results typically point me to foxy webpages:
Thanks for the reply! I’ll admit, I’m definitely not a web developer, so my knowledge on this is somewhat minimal. However, one example that stands out to me is the Isaac ROS documentation. When I search for it on Google, it always defaults to the “latest” version, which is really convenient. It might be worth exploring a similar approach for the ROS 2 docs, where the default could automatically point to the latest active distro, like Humble, when someone lands on the site.
Looking forward to the announcement and any further discussion on this!
that points to the latest distro, that would be great.
Sometimes, when I was linking ROS2 documents in my internal docs, I had to fix on a particular distro (usually it was the latest distro at the moment.) Therefore, when a distro reaches its EOL, my internal docs will be out of date.
Just throwing some ideas out in case you haven’t thought about it. Thanks.
Technically, with the latest URL, you’d be referencing a page whose content may undergo substantial change, rendering your docs out of date too, without you knowing that. But I guess this is anrather theoretical issue.
We have that, it is called Rolling and it isn’t something we recommend new users use. Given that, should we point to Kilted, the release that’s only active for 18 months? Or should it point to Jazzy the current LTS?
What I think people are failing to grasp here is that isn’t a ROS docs problem, it is a Google problem and a user problem. Just because you use Jazzy doesn’t mean having the Jazzy come up higher in search results is the globally correct solution. A good chunk of the community still uses Humble.
Like I said, professional help is on the way. We live in a world that now relies on unbounded SEO jockeying and the solution here is most likely not a trivial path change.
Ironically, isaac_ros leverages ROS2 humble, so if someone were to blindly refer to the latest version or ROS it wouldn’t work with isaac_ros.
This is just to say that, with ROS, it not as easy to decide to what documentation version you’d need to point. Yeah, maybe Foxy is not the best choice, but if you just search with the distro you need you seem to always get the right version as first result on google (just tried, not sure it works with all other search engines).
Maybe one solution could be to point to a common landing page that gives a brief outlook to all the maintained distros and points to each of their documentation.
I also think that understanding that there are different distros and that each one has its scope is one of the basic things to know about ROS.
Maybe you could add a canonical html tag on all the “old” documenation urls that point to the url on the latest stable ros version. This way search engines can de-duplicate the content a bit better, but doesn’t remove the old pages completely.
We have this. The fine folks at Hello Robo worked with @kscottz late last year to put together an entirely new page, which has been live for 6 months or so. It needs help getting a boost in search engine rankings, though. Of course, it’s not perfect, so if you see a problem that needs fixing, let us know!
I agree that Rolling isn’t the best distro to point to by default. My thought was that the site could instead default to the latest LTS release, since that’s what I assume most people (myself included) typically use.
The link mentioned above by @gbiggs is excellent! It actually shows up as the top search result for “ros documentation” on Google, but when I search “ros2 documentation” it’s only the fourth result.
I’m not familiar with what’s involved in getting the newer LTS docs or the ROS Documentation home page to rank higher in search results, but I wanted to start the conversation to see if it’s possible. I really appreciate everyone who’s taken the time to share thoughts on this!
From my limited SEO knowledge, I do not think there is any way to magically know if it should point to rolling, or the latest non-rolling release, the latest LTS release, or the currently “most popular” (definitions will vary) release. I think we just need to agree on something and I also think the latest LTS release makes the most sense.
Beyond that there doesn’t seem to be a strong convention on how this gets handled, but ROS users are used to C++, Python, and Ubuntu so let’s look at them
Ubuntu - Different page per release, but you can edit the url to swap 22.04 for 24.04. They do map a lts page (e.x. Sound problems ) to the 24.04 content, which probably also has good SEO nuances.
So if we want to pick something most similar to other things Ubuntu’s approach makes sense. Beyond that, we could add a note to the docs encouraging people to install a Redirector extension (here is one for firefox and one for chrome) and set up a regex rule they can modify as they switch between projects on diff repos. I just tested out this regex binding and it is working for me.
From
^https://docs.ros.org/en/[^/]+/(.*)$
To
https://docs.ros.org/en/jazzy/$1
Of course, this might backfire if pages get renamed without redirects between versions, or your search engine points you to a rolling page that doesn’t exist for your distro, etc though.
Also this pattern currently triggers but does not work for APIs, such as ros 2 solidprimitive which google points me to http://docs.ros.org/en/noetic/api/shape_msgs/html/msg/SolidPrimitive.html as the ROS 1 API links are dominating SEO. But I think the rule could be updated to convert the link instead to https://docs.ros.org/en/jazzy/p/shape_msgs/ instead with some more GPT regexing.
