This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- RoboComp
- Technical writer:
- Le Thai An
- Project name:
- RoboComp’s basic components
- Project length:
- Standard length (3 months)
Project description
Motivation
RoboComp is one of the well-known robotics frameworks for research and practical applications. The robocomp repo includes a wide range of components (maintained in smaller repo named robocomp-robolab) for different robotic applications such as motor control, localization and mapping, navigation, recognition, etc. However, the components’ repo lacks of detail documentations for compiling or usage of each component, hence the limited usability for new developers. This proposal aims to solve this problem by documenting crucial components of RoboComp as well as compiling an example usage document for combining different components to solve a specific robotics task. The detail of documentation process will be discussed in the next section and then followed by milestone section for planning the time frame to complete the project. Finally, some notes about the documentation process are mentioned.
Description
As mentioned, this project has two main goals:
- Document detail description, compilation and installation, configuration, usages and known issues regarding to each component in RoboComp
- Write an example guide that utilizes different components in RoboComp environment to solve a specific robotics task, i.e localization.
Most of basic components in robocomp-robolab repo currently lack of detail instructions of how to compile and how to use in different parameter configurations. This creates a huge obstacle for new developers who want to use components in their project or contribute to the framework. The reason is that many components are a wrapper of external driver or libraries which have many dependencies, which makes compiling and installing task difficult. Moreover, many components wrap complex device driver (i.e generic hokuyoComp) to provide message interface in RoboComp which requires device specific knowledge to tune the parameters.
Hence, the need for detail documentation, which encompasses device descriptions, dependencies resolving and usages, is essential for open-source contribution. An example of my work hokuyoComp component document is found in the link:
https://github.com/anindex/robocomp-robolab/tree/master/components/hokuyoComp
To write a concrete and detail component documentation using top-down approach, one must at least be able to experience the content written in that document, because the final purpose of documentation is to transfer working knowledge to inherited developers. The proposed structure for each component doc is presented as follow:
- Description
- Compilation and Installation
- Configuration parameters
- Starting the component (usages)
- Known issues
In the example, one firstly gathers information about the Hokuyo sensor specification, reads through the component code to understand the picture of component functionalities in order to write component descriptions. Next, understanding of RoboComp environment and knowledge of device specific parameters as well as library dependencies would help documenting compilation, installation and configuration process of the component. For instance, compiling hokuyoComp needs old liburg0-dev deb package from Ubuntu 14.04, but the deb package is removed from Ubuntu PPA in later version, thus we must do the workaround for compilation as stated in the doc. In this process, we can also record known issues to speed up debugging for new developers. Finally, component usages for different use scenarios is documented for easy integrating the component to RoboComp landscape for different robotics tasks.
Milestones
This section plans an initial time frame for completing the mentioned goals of the project. We will select component docs to write based on categories (i.e camera components, laser components). The current estimation of time for completing components doc is based on time completing example hokuyoComp docs. The time table is as follow:
Aug 1 - Sep 1: Community bonding:
- Setting up weekly meeting for establishing project scopes as well as expectations from both writer and mentors.
- Getting deep understanding in RoboComp framework.
Sep 2 – Nov 2: Writing docs for each component in robocomp-robolab repo with iteratively refinements between mentors and writer via meetings (expected to complete most of the undocumented docs)
Nov 2 – Nov 26: Writing general doc as an example for utilizing different components to solve a robotics task.
Nov 27 – Nov 29: End of project reports.
After GSoD 2019: I would like to stay connect with RoboComp to further improve and maintain my works.
Final notes
It is essential to write a general example of how to integrate different components in RoboComp environment for users to understand the big picture of RoboComp functionalities. This example doc will be discussed further with mentors to decide what robotics task is suitable depending on current implementation of RoboComp.