This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Open3D
- Technical writer:
- Rohan Rathi
- Project name:
- Technical Documentation of Python & C++ API
- Project length:
- Standard length (3 months)
Project description
Synopsis:
The project will be divided into 4 parts: Upgrade and extend Open3D contributor’s guide Complete Python API documentation Complete C++ API documentation High-level docs of core data structures
Description:
In my project I plan on breaking the project into 4 parts:
I plan on completing and updating the contributors guide for newcomers that provides a comprehensive step by step guide on how they can build the source code, build the documentation and join the developer community. In addition to a written guide I intend to make a video showcasing the exact steps on how to build the source code for the youtube channel. I will also add a guide on how new developers can contribute to the documentation by making changes to the source code built by sphinx using pybind and doxygen.
Extend the Python API documentation. Currently the Python API contains basic docstrings for the classes and member functions that provides a vague description of the functionality. I plan on rephrasing the Python API documentation which makes the API easier to understand and the functionality clearer. I also intend to add links to the relevant 3D graphics concepts used in different areas (Eg: Intrinsic matrix used in Camera)
Complete the C++ API documentation. Currently there’s no equivalent docstrings in the C++ documentation as compared to the Python documentation. I intend to document in detail the classes and their associated member functions and data members .
High and low level docs of the core data structures. I intend to understand the code of various data structures such as TriangleMesh, LineSet, Octree and add comments in the codebase, both for new developer understanding and any users. As well as provide high level documentation on the usage and concepts involved in the structures by improving the tutorials. I will provide in detail examples of the usage and add relevant links to the concepts involved in the structures. If time permits I will then work on the more simpler tasks like documenting how to perform certain tasks that can help newcoming users get affiliated with the software.
Project Schedule-
1 August - 1 September:
Get acquainted with my mentor and discuss in greater depth the level of documentation required at different parts of the codebase and also discuss how in depth to go in the low level vs high level documentation. I’ll also spend this time understanding the codebase and study the concepts so that I can document them better.
Week 1 & 2:
I will update and extend the contributors guide. I will improve the documentation on how to build the source code. I will also add a documenters section on how new contributors can help in documentation. I will also make a youtube video specifying step by step how to build the source code.
Week 3 - 5:
I will work on extending the Python API. Rephrase the existing documentation and write in detail documentation of the existing members. I will also add relevant links to related concepts so that users can acquaint themselves better with the concepts involved.
Week 6 - 8:
The current C++ docs are incomplete for most part of the library, so I’ll spend most of the time filling in the C++ docs
Week 9 - 11:
During this period I’ll be working on the core data structures. Restructure the tutorials of each data structure, provide a high level overview as well document example usage details.
Final Week:
I will use the final week to prepare my final report of the work done during my 12 week documentation period. I’ll also spend this time to review and finalise the documentation.