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, docs.ros.org. 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 index.ros.org 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