-
Notifications
You must be signed in to change notification settings - Fork 0
GSoD
This document describes the project proposal created for the 2024 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.
Looking for GSoD 2023? See this page instead.
OSRF 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, the Gazebo simulator, and the Open-RMF system that enables robotic system interoperability. 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. 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.
The Robot Operating System (ROS) is a set of software libraries and tools that help you build robot applications. From drivers to state-of-the-art algorithms, and with powerful developer tools, ROS is used by tens of thousands of roboticists to develop robotics applications. ROS is used in all manner of robots: educational robots like TurtleBot4, agriculture, manufacturing, logistics, vehicle autonomy, and space exploration.
Gazebo is a simulation platform created by the OSRF and it is often used by ROS developers to simulate their robots. The latest ROS release, ROS 2 Jazzy Jalisco, will include Gazebo binary packages that work out of the box with ROS. Bloom is tool used by ROS developers to build and release their ROS code to the broader ROS community as a binary package. Bloom doesn't necessarily need to be used with ROS, but that's how most people use the tool.
ROS is a large project, with a number of affiliated projects that are critical to the success of our end users. Robot Operating System (ROS) is also currently in the process of transitioning from its first major version, ROS 1, to its second major version ROS 2. With a major version change ongoing, and lots of affiliated projects, it is difficult for new users to find the appropriate resource when they need it. This project seeks to wrap up some loose ends, migrate some existing content to more modern platforms, and improve the overall user experience, especially where ROS users are attempting to perform tasks that span multiple tools released across multiple versions. To do this we need a student to assist us in migrating documentation between platforms, cross referencing the updated resources in our documentation, and updating these documents where appropriate.
For this Google Summer of Docs 2024 we want to accomplish three main goals:
- Furnish ROS users with the appropriate Gazebo references in the Gazebo documentation.
- Migrate our Bloom documentation to ReadTheDocs from the ROS 1 Wiki, and provide pointers where appropriate in docs.ros.org.
- Migrate a subset of our existing ROS 2 design documents into the core ROS documentation
GSoD students interested in working on this project will work closely with their mentors to develop a plan to complete the three tasks outline above. A normal week of work will involve meeting with the mentor twice a week to review the steps required for the task at hand documents. The mentor will work with the student to outline the necessary changes to the documents and what updates might be necessary in the migration process. A good student candidate should be familiar with the Github pull request workflow, Markdown and Restructured Text syntax, and elementary HTML syntax. Students should have a strong command of the English language and a clear and concise writing style. As we'll be migrating some content experience with tools like PanDoc is a big plus!
As of ROS Jazzy, Gazebo will ship with ROS as a pre-built binary. Despite this, many users still have difficulty switching between simulated and real robots and creating their own simulated robots. Unfortunately the core documentation for ROS does not overlap substantially with Gazebo and there are very few combined guides on docs.ros.org (this tutorial is the only existing tutorial on docs.ros.org). We believe adding a few more pointers from the docs.ros.org to the Gazebo documentation will help users find the information that they need. For this part of the project the student will work with the mentor to identify important Gazebo documentation resources and add an index page on docs.ros.org to the relevant Gazebo resources. We anticipate that this project will take the student about a week and help familiarize them with docs.ros.org pull request process, Sphinx, and ReStructured text.
Bloom is a critical tool in the ROS ecosystem. Unfortunately, the primary Bloom documentation is currently located on the ROS Wiki. For this part of the project the student will migrate the existing Bloom documentation on the ROS Wiki to Read The Docs using a tool called PanDoc. Where necessary the student will work with the mentor to update this documentation where appropriate. Once migrated the student will work with the mentor to update the relevant sections of docs.ros.org to point to the updated Bloom documentation. For this part of the project the mentor may opt to co-write a small number of new user guides with the student to address potential shortcomings with the existing Bloom documentation. We anticipate this project taking one to two weeks, and it will help familiarize the student with using a tools like PanDoc to migrate documentation.
The ROS 2 transition process started in earnest in 2017, and should be completed by 2025. As part of the early development of ROS 2 we created a series of community design documents. These design documents were used to drive community discussion and educate the broader ROS community about the ROS 2 effort. As ROS 2 has matured the bulk of our documentation efforts have moved to developing the ROS 2 documentation. As such, the ROS 2 design documents have languished and become partially out dated. The design documents have also become a point of confusion for the broader ROS community, and current ROS 2 implementations may differ from the original design documents. However, many of these design documents still contain information that remains relevant to the ROS community. The ROS team has made the decision to update these documents and move them into existing ROS documentation. We are seeking a GSoD student to assist us with transitioning content from these design documents into the more widely used ROS 2 documentation. This process should largely involve moving a subset of the existing design documentation to docs.ros.org, and where appropriate updating these documents to reflect the currently used designs. We anticipate this project taking the majority of the student's effort.
Mentors and GSoD students will meet on a daily basis to discuss their progress, evaluate recent work, and discuss future articles to transition to the ROS 2 documentation. Students will be given regular feedback on their progress by their mentors, who will review and evaluate each document before it is merged into the ROS 2 documentation. Success for this project means making sustained, daily contributions to the ROS 2 Documentation, and Bloom documentation, usually a few articles a day. These new works will borrow heavily form the original ROS 2 design documents, or be migrated directly from existing documentation, but may need to be updated to reflect current development processes, or to address other shortcomings. The resulting documents should be clear, concise, and easy to read. The newly created documents and organized in such a way that they match the current ROS 2 documentation information architecture.
| Budget item | Amount | Running Total | Notes/justifications |
|---|---|---|---|
| Technical writer interviews with the developers, new tutorials, and post-validation with developers |
$6000 | $6000 | |
| Mentor stipends | 500 | $7000 | 2 mentor stipends x 500 each |
We have significant experience generating documentation and tutorials. ROS 1, the older version of our flagship project, uses a wiki as its primary documentation resource. For the latest version of ROS, ROS 2, we autogenerate API documentation from source code using RestructuredText and Sphinx, and it is published on docs.ros.org. The source code for docs.ros.org is publicly available on GitHub. Additional ROS resources, including our user forum, our Discord server, social media accounts, and our video archive can be found here. Gazebo, our simulation platform that is often used by robot developers can be found at GazeboSim.org and the source code can be found here. The pull request process and tool chains used for this documentation varies between the projects.
Open Robotics, also known as OSRF, has successfully participated in multiple editions of the Google Summer of Code program during the years 2013, 2014, 2015, 2016, 2018, 2019, 2020, 2021 and 2022. We also participated in the 2020, 2021 and 2022 editions 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.