I’m running into a bit of a weird problem. Maybe it’s more of an observation. There are times where I struggle to find the documentation for ROS code on google.
Take the following examples:
tf2::BufferCore::lookupVelocity: The search query I came up with on google ros tf2 lookupvelocity returns no relevant results on the first page. tf2 kilted lookupVelocity also returns nothing. tf2 buffercore lookupVelocity lists the documentation from jade, foxy as the first two options but neither version of those documentation pages has lookupVelocity. Even a query like tf2 “lookupvelocity” does not yield any results. From a git blame, lookupVelocity was
Launch python documentation: ros2 launch python includelaunchdescription yields only examples, stack exchange questions and no actual API documentation.
I noticed very clearly that google never gives me ROS source code, and very often outdated API documentation pages. This is really frustrating as it takes longer than I expect to get answers about very normal functions.
I’m really not sure what’s causing this. Is it just bad SEO? Is no one linking to ROS2 docs on the web and so google doesn’t prioritize them? Am I just bad at googling? I’m curious if other people have noticed this. It’s making me feel a little crazy
It looks like part of your message about git blame got cut off.
There were some recently announced OSRA efforts on improved docs which I hope involves some effort on improving SEO as I also run into this. Mainly when looking for message definitions.
For finding message definitions what has helped me is specifying the site for my search, e.g. “site:Index of /en/jazzy/p posestamped” (substituting jazzy with your humble+ distro of choice) and then it won’t return ROS 1 docs.ros.org links or pre-humble https://docs.ros2.org/foxy/api/ links.
Since you can directly search a distro via site, this is less helpful, but I will mention you could combine that with a Redirector plugin for your browser ( Update Default ROS 2 Distro on ROS Documentation Site - #15 by nathanbrooks ) to redirect your URL to your distro of choice (unless for some reason the package has moved/doesn’t exist for your distro).
So for your example, I do “site:https://docs.ros.org/en/kilted/p buffercore” (“site:https://docs.ros.org/en/kilted/p buffercore lookupvelocity” returned nothing)
There’s a useful link that I hadn’t seen before in that thread: http://index.ros.org/ that seems to link the actual documentation, including the two queries that I wasn’t able to solve with google. It would be great if the SEO on that content could be improved. As great as reading source code is, google is still my primary tool for finding information about code and it is certainly super important for people who are new to ROS.
I think the conclusion here is that the documentation does exist on the internet, but it’s either not being indexed, or not getting a high enough SEO score to actually be surfaced in searches. The documentation I was looking for in tf2 is hosted here: Class BufferCore — tf2: Humble 0.25.17 documentation but if I search site:docs.ros.org lookupVelocity that page doesn’t come up.
@Katherine_Scott (not sure if I’m @’ing the right person, please feel free to not respond or tag someone else) do you have any feedback on on-going efforts for this?
Much of the work will be focused on documentation structure and infrastructure (particularly, what is known as an information architecture), aiming to provide a common information architecture that all projects can build on. We will also be putting funding into improving the searchability of documentation (both via external search engines and internally), the usability of the documentation when used via LLM-powered agents, and supporting structured “learning pathways” through a project’s documentation.
That work just kicked off in late July so there are no updates at this time.
What’s really frustrating for us is that we have very little control over the results that appear in search engines or in LLM models, yet we are often the ones getting blamed for their poor performance. Additionally, forks of the ROS documentation (as opposed to mirrors) and independent translation efforts (as opposed to addressing translations in the canonical documentation) are probably exacerbating this problem.
All of this is too say we always need contributors to the ROS 2 Documentation, especially from individuals who have experience improving SEO. There’s also a lot of work still to do to improve package-level documentation and tooling available for ROS Index (huge shout out to @rkent for his on-going work in this direction). As @rkent can attest we also really need more contributors and reviewers on that front.
If this is something you are passionate about and you would like to have a HUGE positive impact on the ROS community our documentation crew could really use your help.
There have been a couple of issues (1, 2) filed on rosindex pertaining to how it interacts with search, but to realistically work on the issues you would need access to the Google analytics for the site, which access I don’t have.
We also badly need IMHO a way to use a “latest” tag as a placeholder for current documentation, and find ways for search engines to link there rather than to a specific rosdistro. Most of my Google searches seem to point to the ‘foxy’ distro now. A link like ‘http://docs.ros.org/en/latest/p/tf2_geometry_msgs/’ should go to kilted, not “Not Found” as now. That’s an infrastructure issue.
Generally searches for specific packages are quite efficient now on rosindex, so if you know the package you are looking for, or even a piece of its name or description, it is quite easy to find that.
I noticed already that docs.ros.org has no robots.txt or sitemap, so I bet it’s not indexed by google. I chatted a bit with a friend who did SEO in a past life and he suggested going straight to the google search console to at least see that the site is being indexed at all (which given my test on site:docs.ros.org I think is the case).
