ROS Resources: Documentation | Support | Discussion Forum | Service Status | Q&A

Request for Comment: Per Package Documentation Requirements

We’re looking for feedback on our requirements for our package documentation project for ROS 2. We’d like to hear ideas from package maintainers and users of ROS 2 documentation, especially if it seems like there’s a crucial blindspot in our assumptions about per-package documentation necessities. At this time, the document is not going to address implementation details, only high-level requirements.

“Per-package”, “package-specific”, and “package documentation” all refer to any docs solely focused on a single package, including auto-generated content like API docs as well as manually created content like readmes, changelogs, tutorials, etc.

We envision all documentation, including per-package docs, hosted under a single domain, Package documentation will be maintained only within a package’s repository, and automatically built into the documentation site with the rest of our generic ROS 2 content (what’s on now), organized intuitively through the site’s structure and under sensible URLs. We hope this will encourage consistent, quality package documentation, and address the issues of discoverability and spread that ROS 2 docs have seen so far.

The requirements and context behind each are listed in this design document.

Please leave a comment on the pull request with your feedback.

Note: These requirements do not address the docs site as a whole or the generic documentation. We are also preparing updates for the other elements of the hosted documentation such as extending support for versioning and internationalization, as well as consolidating the documentation to be more accessible. With that in mind, please focus your feedback on per-package documentation


The next iteration of the design document has been posted for review:

Please comment on the PR with any feedback.