GSoD21
This document describes the project proposal created for the 2021 Google Season of Docs. This project is based on the GSoD exploration document, where we discussed multiple documentation ideas. If you have any questions please message gsod AT osrfoundation.org.
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 simulator (http://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/). We believe that Google Season of Docs will help to encourage more contributions and further promote a sense of community-driven software. As a bonus, the robotics community will also get new and exciting documentation.
ROS 2 currently has a pretty good set of beginner tutorials. Once a user has gotten through the beginner tutorials, however, ROS 2 is currently lacking a coherent set of guides for some of the intermediate concepts.
The goal of this project is to write technical articles explaining some of the intermediate concepts. To accomplish this goal, the writer will have to do interviews with members of the ROS 2 development team to understand the technical concept, and then put that concept together into a easy-to-explain article.
At the end of this project, one or more of the following tutorials should be complete:
- tf2 (alex)
- Launch (audrow)
- rostime
- QoS settings (alex)
- Executors / spinners
- Composition
- Lifecycle Nodes
- Logging (audrow)
- RQt*
- RViz
- rosdep (alex)
- Build system (ament) (audrow)
- Docker (audrow)
- Debugging
- Testing (audrow)
In late 2020 we looked at the most viewed and most unanswered questions on answers.ros.org. The first chart shows the question tags that were not answered frequently on ROS Answers.
This plot shows the least frequently answered question tags in 2020. These are areas that could use additional documentation.
We also examined the most viewed question tags on ROS answers. This plot shows topics that are searched for / viewed on ROS Answers.
After the projection completition we plan to advertise the new intermediate level tutorials among our community. A few months later (around late 2021), we plan to generate similar plots to confirm that the topics captured in the new tutorials are less frequently asked and, more importantly, the questions associated to these topics are more frequently answered.
| Budget item | Amount | Running Total | Notes/justifications |
|---|---|---|---|
| Technical writer interviews with developers with the developers, new tutorials, and post-validation with developers |
$6000 | $6000 | |
| Mentor stipends | 500 | $7000 | 2 mentor stipends x 500 each |
We have quite a few experience generating documentation and tutorials. ROS, one of our main open source projects, uses a wiki that any developer can update when releasing their own packages.
In addition, we autogenerate API documentation from the source code and it is published on http://docs.ros.org/ .
Other examples are the tutorials that we created for our 3D robotic simulator project, Gazebo:
http://gazebosim.org/tutorials
Most recently, a new documentation system was created for a group of libraries named Ignition Robotics that we also lead:
https://ignitionrobotics.org/docs
All these projects are open source and the documentation is produced in different ways. Sometimes it is an open wiki and other times requires a pull request, review, and multiple approvals.
Open Robotics has successfully participated in multiple editions of the Google Summer of Code program during the years 2013, 2014, 2015, 2016, 2018, 2019, 2020 and 2021. We also participated in the 2020 edition of the Google Season of Docs. We can leverage our previous experience to keep the technical writers involved in our community during and after GSoD, keep the mentors engaged with them, and also make sure that all the technical writers stay on schedule to complete the goals of the project.
If you meet the general requirements and are interested in working on the OSRF project during the Google Season of Docs, you can apply by:
- Sending an email to: gsod@osrfoundation.org , with the subject line: GSoD Application
- Your application should include the following information:
- Your name
- A phone number
- An email address where we can reach you for daily communication
Please list relevant technical courses you have taken. In particular, we are interested in your background in:
- Robotics
- Software engineering
Please list any experience you’ve had writing technical documentation. For each example, please include a brief description of the overall project along with the specific contributions you made and when you made them.
In addition to the above information, we are interested in concrete examples of your work, which may include:
- Documentation samples: please send an example of documentation you have written that you are proud of; be prepared to answer questions about it.
- Publications: if you have participated in undergraduate or graduate research, please include a copy of any relevant publications.
- Specialized skills: if you have experience/skills in particular areas that you believe would be useful to one of our projects, please let us know.
- Personal website: if you have a website that discusses your research or other projects, please include a link.
- Personal projects: do you have a website, github/gitlab repo, blog post, video, or other work you think we would find interesting and relevant? Please include it in your application.
- References: names and contact information for people you have worked with who can recommend you.
In a paragraph or two, describe your interests and background. Please tell us why you’d like to work on our GSoD project, what topics you would like to cover, and why you think it is important to cover them.