[ros-users] [Discourse.ros.org] [Next Generation ROS] ROS 2 documentation home moving to index.ros.org/doc/ros2

Dave Coleman ros.discourse at gmail.com
Sat Oct 27 01:51:55 UTC 2018





> Another change is that the documentation is now using the [reStructuredText format](http://docutils.sourceforge.net/docs/user/rst/quickref.html) instead of markdown. Like with the rest of the ROS 2 development process this will help us improve the documentation by letting us have it go through the same type of review process that were applying for code changes.



Sorry if I missed [the requirements doc](https://github.com/ros2/design/blob/gh-pages/articles/080_ros_documentation_system.md), but can you better help us understand why reStructuredText was used instead of Markdown? You say its for the "same type of review process" but you can actually have that for either formats. ReStructuredText, however, is a lot more complicated to learn IMHO and is clunky.



Markdown seems to have become the dominant format in recent years due to its simplicity. For example [here at Discourse](https://meta.discourse.org/t/developers-guide-to-markdown-extensions/66023) and of course all pull requests and issues at [Github](https://help.github.com/articles/about-writing-and-formatting-on-github/).



In reality, since Github is the dominant ROS code hosting platform, using Markdown (what github uses) would let it "go through the same type of review process that we're applying for code changes".



For the MoveIt! project, we currently use Markdown for the website and reStructuredText for the tutorials, and the reStructured text and much trickier and people routinely (myself included) make mistakes with it. 



I realize that reStructured text allows you to do a lot more complicated Python scripting, but I'm not convinced we need that for the global ROS2 docs. Do you plan on committing code files to this repo as well? Instead I'd prefer increased accessibility for people to contribute, and consistency with what we're using on Github and Discourse.











---

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









More information about the ros-users mailing list