search

ros2 / design

Design documentation for ROS 2.0 effort
http://design.ros2.org/
Apache License 2.0
215 stars 194 forks source link

Per-Package Documentation #301

Closed maryaB-osr closed 3 years ago

maryaB-osr commented 3 years ago

Signed-off-by: maryaB-osr marya@openrobotics.org

ros-discourse commented 3 years ago

This pull request has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/request-for-comment-per-package-documentation-requrements/16699/1

33thou commented 3 years ago

As a newcomer to ROS2 coming from the Python ecosystem, it's often surprising and frustrating to come across github repos for packages with no documentation in their Readme files. In general the relationship between ROS packages, locations in ros.org, and repos in Github is super confusing and it's often not clear to me where to find documentation, file an issue, or ask a question. This is especially hard because of the highly federated mapping to many github organizations and child repositories, so sometimes the hierarchical structures are unclear.

Compare with the PyPi website. Packages have relatively simple introductions and metadata there, but in general package maintainers are encouraged to create robust docs directly in Github, or using a system of choice like readthedocs or a static site generator.

If docs.ros.org is being set up as the canonical way to find documentation that seems useful, but I would think two things are important:

  1. a systematic way to link to an external homepage and docs page if the package maintainer chooses to put their docs elsewhere
  2. a systematic way to generate README.md files in github which link to relevant locations in *.ros.org

thanks for considering!

P.S.: as an aside, I've found index.ros.org to be really awkward to use. I was browsing around looking for packages supported by Foxy related to kalman filters, sensor fusion, IMUs, 3D cameras, and visual odometry. Searching is super confusing because it just gives names of packages with no descriptions or any other useful context like popularity or frequency of updates.

ros-discourse commented 3 years ago

This pull request has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/new-ros-ecosystem-paper/17261/8