Why don't we use Docusaurus / Nextra ? A propsective idea

General
1

Documentation

Why don’t we adopt the usage of Nextra or Docusaurus and remodel the ROS wiki as it is considerably harder for any beginner to setup ROS?

I can volunteer for this as well if needed.

1 Like
2

The ROS wiki is deprecated, and only used for ROS 1. For ROS 2, we already have the documentation in restructured text at GitHub - ros2/ros2_documentation: ROS 2 docs repository, and we build it with Sphinx. The output is hosted at https://docs.ros.org.

If you have any things you’d like to see improved on that site, feel free to open pull requests and we are happy to review them.

4 Likes
3

I’m all for improved documentation and help resources (and I think everyone else is all for it, too)! But I don’t think using a different tool to present the text is going to be the fix. If people are having trouble with a tutorial, changing the format of the tutorial probably won’t help. As far as I can tell, these tools are basically the same as Sphinx.

You’ve mentioned being open to volunteering: I think a really helpful way for you to help here would be to describe what specific part of getting started you felt was tricky, so that these tutorials can be addressed (by you or someone else adding a new one, or editing existing ones).

7 Likes
4

Let me explain why the change of tool was relevant.

The structuring/visibility of certain commands and instructions are significantly better which makes the whole installation flow smoother, I’ll demo an example as images here:

Nextra

image
image2188×1240 130 KB

Docusaurus

image
image1976×1778 181 KB

I am certain that the Ubuntu 20.04 error with ROS Noetic can easily be highlighted with warnings like that which makes life super simple

5

Given that ROS 1 is only supported for the next 1.5 years, I don’t think we should spend significant time on restructuring the documentation.

For ROS 2, the Sphinx output already looks extremely similar to Nextra or Docusaurus, so I don’t see a very compelling reason to change tools there. Of course updates to the contents are very welcome.

2 Likes
6

Sphinx can do warnings/notes too, and the ROS 2 docs use that (for example, here).

2 Likes
7

I agree with this because ROS 1 is anyways going to be deprecated

8

I’m up for helping the wiki and documentation for ROS 1, will soon catch up with ROS 2.

9

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