-
Notifications
You must be signed in to change notification settings - Fork 0
gsod_2021_case_study
Project main website: https://www.ros.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 Ignition simulation library suite (http://ignitionrobotics.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 create a set of ROS 2 tutorials for intermediate users. https://github.com/osrf/osrf_wiki/wiki/GSoD21
The Open Robotics team heard about the Season of Docs program last year from Google's Open Source Programs Office. We internally discussed the 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:
- Alejandro Hernández (mentor)
- Audrow Nash (mentor)
- Carlos Agüero (org coordinator)
- Shyngyskhan Abilkassov (technical writer)
Shyngyskhan sent us an email expressing interest in working with us through the Season of Docs program. We thought that Shyngyskhan’s experience in a previous Season of Docs program, as well as his interest and technical skills, made him a good match for our project. We reached out to Shyngyskhan and four other people that expressed interest in our project and invited them to write some documentation on a small programming challenge that involved using and understanding ROS 2’s publishers and subscribers. After reviewing their solutions, we scheduled video calls with the top three applicants. From these interviews, we thought that Shyngyskhan seemed like the best fit. In addition to his previous experience, Shyngyskhan seemed to be a strong communicator and to be organized, which gave us hope that he would do well in this program.
To coordinate with and guide Shyngyskhan in his progress, we had monthly meetings. These monthly meetings were helpful to discuss technical questions and to make sure that Shyngyskhan was happy with what he was working on.
Because Shyngyskhan’s time zone only overlapped a few hours with most of the members of the Open Robotics team, we mostly coordinated with Shyngyskhan through Slack and Github. In the case that there was anything urgent to discuss, we gave Shyngyskhan a link to a calendar to schedule last minute meetings with Alejandro and Audrow.
We were very happy working with Shyngyskhan, who has contributed substantially to the ROS 2 tf2 and ROS 2 launch documentation.
While we waited for the Season of Docs program to announce participating organizations, the Open Robotics team collected a list of parts in the ROS 2 ecosystem that would benefit from additional documentation.
Once we got the good news that we were selected for the 2021 Season of Docs, we waited for applicants to arrive. We then went through all of the applicants, considering them on several relevant dimensions. After discussing our impressions of the applicants, we reached out to the top four applicants with a small programming and documentation challenge. We gave them around a week to complete this. We then reviewed their submissions to our challenge and then invited the top three applicants to have a video interview with us. After the interviews, we decided to offer Shyngyskhan the opportunity to work with us for this program, for which he accepted.
Around a week after Shyngyskhan accepted the position, Alejandro and Audrow met with Shyngyskhan to get him started contributing to the ROS 2 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 Apr 19, 2021: Review applicants
- Apr 23, 2021: Send out programming challenge to top applicants with a deadline of Apr 29, 2021
- Apr 30, 2021: Offer interviews with the top applicants after reviewing their programming challenge solutions
- Week of May 3, 2021: Interview applicants
- May 7, 2021: Choose candidates and send offer
- May 18, 2021: Initial meeting with Shyngyskhan to figure out what he’ll be working on and coordinate logistics
- Jun 15, 2021: First monthly check in
- Jul 20, 2021: Monthly check in
- Aug 19, 2021: Monthly check in
- Sep 21, 2021: Monthly check in
- Oct 26, 2021: Monthly check in (bumped back due to scheduling conflicts)
- Nov 16, 2021: Final check in and debriefing
- Week of Nov 22, 2021: Write this case study
The major result from Shyngyskhan’s work is that the tf2 tutorials have been ported from ROS 1 to ROS 2. This involved porting code from ROS 1 to ROS 2 from over 20 tutorials, as well as writing new documentation explaining the new ROS 2 code. You can see a full list of these contributions here: https://github.com/ros2/ros2_documentation/issues/1631.
In addition, Shyngyskhan also created a new document explaining the architecture of tf2 and created several ROS 2 launch tutorials. You can find a full list of Shyngyskhan’s contributions here: https://gist.github.com/kurshakuz/67bf4d34a8a838abb77d9ce6e6139d85.
Near the end of this year we intend to look at the popular tags on ROS Answers to see if there is a decrease in tf2 and launch questions.
Anecdotally, we believe this new documentation has made a difference in allowing ROS 2 users to work with tf2 and ROS 2 launch, as it seems that there is less talk in the community about glaring gaps in the documentation around tf2 and ROS 2 launch.
We are very pleased with the outcome of our Season of Docs project and consider it a success. The new documentation is clear and helpful, and the new document on tf2’s architecture is a great addition to ROS 2’s documentation, as tf2 is a fundamental component for many robotics applications.
One thing that we were pleasantly surprised by is how useful Github’s pull request reviews were in mentoring Shyngyskhan during the process of writing documentation. It was easy to make corrections, add links to recommended reading, and to reference other code or documentation. The asynchronous nature of pull request reviews worked well with us, especially with the differences in time zones between the Open Robotics team and Shyngyskhan.
Overall this project went terrifically. We achieved a substantial amount of progress in improving the ROS 2 documentation and our anecdotal experience so far supports the idea that our metrics are inline with our goals.
A huge part of this success was how lucky we were to work with our great technical writer, Shyngyskhan Abilkassov. He was hardworking and organized, and quickly learned ROS 2 and C++ well enough to contribute documentation. His general interest in ROS 2 and robotics made it easy to find work that was agreeable to him, and the quality of his work generally improved as he learned more about the technologies involved and gained more experience writing tutorials. We are happy for Shyngyskhan’s contributions to our community and hope that he stays a regular contributor to the ROS 2 ecosystem.
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 Shyngyskhan, 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 Shyngyskhan 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.