Why is the ROS wiki only for ROS1?

General
1

Continuing the discussion from When ROS2 Wiki?:

As ROS2 grows more and more mature, and the main development for many packages shifts to ROS2, it is rather annoying to lookup ROS wiki pages for packages, only to have them only display ROS1 docs, even if that package is actively being developed for ROS2. What is the reason for blocking ROS2 versions from publishing docs to the ROS wiki? ROS2 has no equivalent right now. The package index doesn’t display docs as uniformly as the ROS wiki does.

11 Likes
2

Rather than using the ROS wiki (which is ROS 1 specific as you pointed out) have you tried checking through ROS 2 Documentation. On this page you can find lots of useful references to distributions, packages, etc. of both ROS 1 and ROS 2. Specifically to your point of looking up packages, you may want to try out ROS Index which is referenced on the documentation page.

3

My 2c as a fairly casual user of this documentation - I feel like the current approach (as I understand it) is the right direction but a little clunky.
I also want to preface this by noting that I understand that documentation is a difficult thing to manage, especially in a project this large and distributed, so props to everyone who has worked hard on it so far!

I think it makes sense to avoid duplication of information, and the GitHub readme for a repo is quickly becoming the first place to look for documentation on anything, not just ROS packages.

The ROS Index seems to show this readme as the default which I think is great (I’ve not paid attention to how it handles sub-packages in repos etc, presumably a separate readme at the root of each package?) This way the documentation is kept close to the code, and in all the places people would normally expect it to be.

But accessing it I feel is a bit clunky. Firstly, the wiki tends to rank highly on searches, so you often hit it first. The wiki helpfully tells you in the sidebar:

The ROS Wiki is for ROS 1. Are you using ROS 2 (Dashing/Foxy/Rolling)? Check out the ROS 2 Documentation

So you click the documentation link and it takes you to the main ROS docs, which are great but also probably have nothing to do with the package whose wiki page you were just on, and of course no amount of navigating there is going to get you to them - instead you need to go to the index.

So you eventually find the index page for your package (somehow) and the readme is helpful, but you think “it would be nice if there were more tutorials/guides on this”. You notice the Tutorials tab and click it, which takes you back to the wiki (but to the package’s tutorials sub-page)!

See ROS Wiki Tutorials for more details.

Now, this is a reasonable link to have since the Index is also relevant for ROS 1 packages, and the wiki often has useful information for both ROS 1 & 2. But it’s not at all clear when you’re clicking on it that it may be outdated information, and because it’s auto-generated it may link to a page that doesn’t exist (such as my example above).

I’m left unclear as to where additional tutorials/guides for ROS 2 are actually meant to live. I think the most reasonable place is as other Markdown files in the repo, and to have way for them to be viewed within the Index but I’m not sure how that would work (I’m just realising, perhaps that is the “Source Tutorials” sub-heading on the Index? If so, is that auto-indexed?)

One other note, there is also the “API Docs” button on the Index page which redirects to an appropriate docs.ros.org URL (regardless of whether it exists). How does one go about having documentation properly indexed there? Is that a thing in bloom/rosdistro?

Thanks again for all the documentation that has been created so far, the content is fantastic (especially docs.ros.org) but sometimes just a little hard to navigate unless you know exactly where to look :slight_smile:

4 Likes
4

I consider both of these advantages (documentation in same repo, no duplication) to be very important as well. In detail, index.ros.org renders the README.md in the root of the package, which is often not the root of the repository. My best practices are:

  • README.md in repository root:
    • List of contained packages with links to the corresponding folders
    • General information on license, quality assurance, etc.
  • README.md in package root:
    • One-liner about and with link to the README.md in the repository root
    • Package documentation in the style of a ROS 1 Wiki page, possibly with link to related packages (will unfortunately lead to the source code folder and not the entry at index.ros.org)

See https://index.ros.org/p/fmi_adapter/github-boschresearch-fmi_adapter as an example.

I agree, it makes no sense. A good heuristic could be to list packages that are dependant packages of the current package and contain a keyword like example(s), tutorial(s), etc. in the name.

This would require that tutorials are published as packages either - probably doable in many cases.

If I remember a past discussion correctly, API Docs are generated automatically now, but only for Humble and Rolling.

https://index.ros.org/ should be promoted much more. Larger projects should consider an entry on the Related Projects page of docs.ros.org, although I have to say that I struggle a bit with the term “related”. I consider Navigation2, MoveIt, ros2_control as subprojects of the overall ROS project. But that’s just terminology …

2 Likes
5

There are a few reasons we decided to move away from the wiki:

  1. The wiki was far too overloaded. The ROS 1 wiki is using MoinMoin, which is designed to serve something like 1000-2000 pages. We are currently serving > 13000, and it is just not up to the task.
  2. It was too easy to make changes to the wiki. This is a blessing and a curse. Because it was easy, it allowed casual contributions. But it also means we constantly have to deal with spam, and it also means that important pieces of information (like how to install the system) frequently get changed. Usually those changes are with good intentions, but they are also sometimes wrong (or only right in certain circumstances). It is far easier to review pull requests before they get in, as opposed to constantly policing changes post-hoc.
  3. Closely related to both above points, when we looked around we saw that most sites nowadays are static sites deployed from a git repository. This gives much better performance, and allows us to review changes.

So going back to the wiki is a non-starter.

That said, I agree with the sentiments that it is not that easy to navigate all of this stuff right now. I think we should better promote index.ros.org (as @ralph-lange said), and also tighten up the navigation from it to make it easier to use. There’s probably other things we can do to make it easier-to-use as well; we’d definitely welcome recommendations and/or pull requests to make that happen.

5 Likes
6

Yeah I think the link:

The ROS Wiki is for ROS 1. Are you using ROS 2 (Dashing/Foxy/Rolling)? Check out the ROS 2 Documentation

is not very helpful at all, since as previously mentioned, much of the time I end up at a ROS wiki page for a package (since the SEO is supercharged for the ROS wiki still for some reason) and the ROS2 docs don’t contain package information.

At the end of the day, it’s not a nice user experience to have out-of-date docs be the first search engine result for most packages. If the ROS wiki has technical limitations, maybe there is a way to deprecate it entirely, but have a system that works for both ROS1 and ROS2, like a better ROS index user experience, as some people have mentioned.

6 Likes
7

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.