ROS2 Documentation

[tfoote]

@mikeferguson I jumped this into a new topic as it’s worth it’s own thread and it’s still an area of active development.

@mikeferguson

Currently, most things seem to be documented in the ros2 github wiki, or the design documents. But now that there is a larger group working on porting things to ROS2, I’m not sure where documentation is supposed to go.

There’s actually a drafted design document about documentation from several years ago design/articles/080_ros_documentation_system.md at gh-pages · ros2/design · GitHub It’s only a draft but lays out a lot of our thoughts on how to help our system scale better than the wiki and associated infrastructure. We have not fully revisited that or tried to fully implement it yet. But for the Crystal release we’re targeting getting some minimum viable products out to help organize the ecosystem. In particular we’re looking to federate the documentation in the same model as we do the code and keep the documentation and the code closer together.

@mikeferguson

Given the flat namespace of the current wiki, along with the maintenance issues of the custom MoinMoin stuff, should there be a separate wiki for ROS2? Is the ros2/rosdistro being parsed anywhere currently? The original ROS wiki push done at Willow was definitely a turning point in ROS adoption.

We’ve been prototyping a new documentation site based on @jbohren @jbohren-hbr 's rosindex.

We have a test site live at https://index.ros.org It’s still a prototype that we’re working on.

If you’d like to see what’s happening please take a look at:

GitHub - ros-infrastructure/rosindex: The source code for generating...

As always contributions are appreciated and welcomed. There are several enhancements that are ticketed but not yet implemented. And if you have other ideas of what could be added or improved please open issues or PRs.

@mikeferguson

Also, I personally find it is pretty hard to locate where the ROS2 version of a particular package might be (for instance, I only recently noticed that there was an RVIZ repo under the ros2 org)

Once the index is up at least things that are indexed should be much easier to find. Search which can get you pretty quickly to ROS Index

@mikeferguson

Do we have any “best practices” for where to put things? I know there is a lot of working going on with the “navigation2” package in ros-planning org, but should we instead have a ros2-planning org?

I recommend keeping code as close to the existing hosting as possible, without being too disruptive. If you’re doing a straight port, we’ve found that having ROS2 branches in the same repository as the ROS1 branches works well. If there’s a significant structural change or a significantly different development team/workflow etc a separate repository can be helpful to keep issues separate. It’s always a judgement call and a balancing act between forks or branches.

In contrast, I’d recommend against creating duplicate organization units. I see that the organizations represents a ROS sub-community and recreating the sub-community structure for a new version of the software doesn’t really make sense. We did separate a lot of things into separate organizations and websites in our early prototyping but that was mostly to keep things cleanly separated so that ROS users wouldn’t accidentally stumble upon early prototypes of ROS2 and try to use it and get confused when it didn’t work, or wasn’t compatible.