[ros-users] [Discourse.ros.org] [Next Generation ROS] ROS2 Documentation

[Tully Foote]

@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.



[quote="mikeferguson, post:1, topic:6475"]

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, Im not sure where documentation is supposed to go.

[/quote]



There's actually a drafted design document about documentation from several years ago https://github.com/ros2/design/blob/gh-pages/articles/080_ros_documentation_system.md 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.



[quote="mikeferguson, post:1, topic:6475"]

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.

[/quote]



We've been prototyping a new documentation site based on @jbohren @jbohren-hbr 's [rosindex](https://github.com/rosindex/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:



https://github.com/ros2/rosindex



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.



[quote="mikeferguson, post:1, topic:6475"]

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)

[/quote]



Once the index is up at least things that are indexed should be much easier to find. https://index.ros.org/search/?q=rviz which can get you pretty quickly to https://index.ros.org/r/rviz/github-ros2-rviz/



[quote="mikeferguson, post:1, topic:6475"]

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?

[/quote]



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.











---

[Visit Topic](https://discourse.ros.org/t/ros2-documentation/6475/2) or reply to this email to respond.