2022 MoveIt Doc-A-Thon
2022 Jan 14
Last Friday the 14th, PickNik had an internal day of working on the documentation site for MoveIt 2. There are a few really large improvements and efforts that we tackled.
API Documentation
There is now API documentation for MoveIt 2 on Foxy, Galactic, and Rolling.
- livanov93 added the configuration and a How To Generate API Doxygen Reference Locally page on the docs site.
- vatanaksoytezer did the work to make it deploy automatically using GitHub actions as part of the site.
- senceryazici added a CSS stylesheet to add a clean modern style to the Doxygen site.
Site Content Redesign
Following the advice of The Documentation System we separated the different types of documentation. This redesign should make it easy for those using the site to find the sort of content they are looking for.
- Tutorials are learning-oriented and guide the user through creating projects using MoveIt to explore the various features MoveIt offers.
- How-To Guides are problem-oriented in that they are focused on helping the reader solve a specific problem.
- Concepts are understanding-oriented and should help those trying to get a deeper understanding to “why” questions about MoveIt.
- API Documentation is information-oriented and serves to help you find specific answers about MoveIt’s API.
- Examples are feature-oriented. These contain examples of how to use specific features in MoveIt. The majority of the content on the site is here because this was the previous format for tutorials.
- Contributing docs are contributor-oriented. This is the place for documenting the contribution process and concepts that are specifically useful when trying to make changes to MoveIt.
Look and Feel
Before this doc-a-thon, we had upgraded the infrastructure of the site to allow us to deploy different versions of the site for the different releases of MoveIt. With that change, we lost the look and feel of the original site, which had been carefully designed to use the same color scheme as the moveit.ros.org website. Dave restored the look and feel of the site and also made other small changes to improve the user experience.
Future Work
Looking through the documentation site you’ll notice a distinct lack of content in the Tutorials and How-To Guide sections. Much of what could go into the Tutorials will come from the Examples sections. The How-To section is a new type of doc that we hope will become more useful as more How-To Guides are written. If you would like to be involved in these changes please start with our new guide on how to contribute to the docs site.