gsod_2022_case_study
Project main website: https://www.open-rmf.org
Organization description: Open Robotics is a leader in a global community of robotics engineers, scientists, hobbyists, and entrepreneurs. We’re committed to developing and supporting open source robotics software, in particular the ROS (Robot Operating System) tools and libraries (http://ros.org) and the Gazebo simulation library suite (https://gazebosim.org). This software is used and developed by people in labs and companies around the world, many of whom will come together for the annual ROS Developer Conference, ROSCon (http://roscon.ros.org/).
The goal of this project was to write technical articles explaining some of the Open-RMF introductory concepts. https://github.com/osrf/osrf_wiki/wiki/GSoD
The Open Robotics team was familiar with the Season of Docs program as we participated in 2021. We internally discussed the 2022 program and created a first document where interested mentors contributed with ideas. Then, the discussion continued and we converged to the final proposal.
The organization coordinator at Open Robotics had previous experience with other programs, such as Google Summer of Code and Outreachy. This past experience helped us estimate the work.
The core team working on this project was:
- Marco Gutierrez (mentor)
- Carlos Agüero (org coordinator)
- Dev Manek (technical writer)
Dev sent us an email expressing interest in working with us through the Season of Docs program. We thought that Dev experience in robotics (including ROS) and programming, as well as his motivation and technical skills, made him a good match for our project. We evaluated Dev and other people's proposals. After reviewing their applications, we thought that Dev seemed like the best fit.
To coordinate with and guide Dev in his progress, we had monthly meetings. These monthly meetings were helpful to discuss technical questions and to make sure that Dev was happy with what he was working on.
While we waited for the Season of Docs program to announce participating organizations, the Open Robotics team collected a list of parts in the Open-RMF project that would benefit from additional documentation.
Once we got the good news that we were selected for the 2022 Season of Docs, we waited for applicants to arrive. We then went through all of the applicants, considering them on several relevant dimensions. After the review process, we decided to offer Dev the opportunity to work with us for this program, for which he accepted.
Around a week after Dev accepted the position, Marco met with Dev to get him started contributing to the Open-RMF project. From there, we met once each month for a check in meeting until the end of the program.
Here is a summary of the timeline:
- Week of May 2, 2022: Review applicants
- May 10, 2022: Choose candidates and send offer
- May 17, 2022: Initial meeting with Dev to figure out what he’ll be working on and coordinate logistics
- Jun 14, 2022: First monthly check in
- Jul 26, 2022: Monthly check in
- Aug 23, 2022: Monthly check in
- Sep 20, 2022: Monthly check in
- Oct 18, 2022: Monthly check in (bumped back due to scheduling conflicts)
- Nov 17, 2022: Final check in and debriefing
- Week of Nov 21, 2022: Write this case study
Dev Manek's work helped update the Open-RMF main installation instructions page as well as the Ros2 "Programming Multiple Robots with ROS 2" Book, that explains the details of the Open-RMF project.
For the first part, installation instructions, there are now per release specific instructions (i.e. 21.09) that help explain the specific of each one of these releases to the final user. It also makes it easier to add future releases as we only need to fork the previous one and add the specific modifications for the new release.
On the second part, the multirobot book, the fleets tutorials where created so now users of Open-RMF have an easy step by step guide to get their robot fleets onboarded, nodes have been documented and questions from FAQ has been integrated into the book.
Under the GSoD program 10 pull requests were made with more than 5000 lines of documentation changed. The number of clones of the main rmf repo has doubled:
Before GSoD:
After GSoD:
The Open-RMF project is in an early stage of rapid growth and continuous changes, this leads to frequent releases, changes in the code and addition of new features. The fact that through GSoD we were able to document the new releases and features that are becoming available has made the onboarding of new users much smoother.
Specially the part that documents the creation of fleet adapters was a well received one. This is an important entry point for many of the Open-RMF users and having well documented tutorials with examples is key in getting them interested in the framework. It also alleviates some of the work on the team as having a clearer and easier documentation helps in reducing the amount of Q&A the team has to address when dealing with third parties.
All in all, we are very pleased with the outcome of our Season of Docs project and consider it a success.
Overall the project went great. We achieved a substantial amount of progress in improving the Open-RMF documentation and the reach out of the software. It has gain a lot of traction among different interested parties and many are already using it or even collaborating with us in its development.
Dev Manek was hardworking and fast to answer any requests from the team. His technical knowledge enabled him to write and at the same time test the tutorials. Even after the project is over he has been helping when asked, ### we hope he stays as a contributor to the Open-RMF ecosystem in someway.
We would advise other projects to do the following:
- Be specific in tasks and feedback. We found we were much more likely to get a good result when we provided clear feedback. If we didn’t really think about what we wanted in a suggestion to Dev, then it wasn’t his fault if his next attempt to address the feedback didn’t meet our expectations.
- Include justification to your feedback. It is important to teach “why” someone should do something, not just “what” they should do. We found explaining “why” helpful to Dev as he could then better understand the intention behind our recommendations and then apply that intention more broadly.
- Be responsive! It is best if the technical writer can get feedback back from you a short time after submitting something for your review. It helps block them so that they can keep moving. That being said, it may be good to agree on a backup task, just in case you have a bit too much to do to be responsive.