Posted by Margaret Maynard-Reid, Machine Learning GDE from Seattle US
A Docs Sprint is a way to improve documentation for an open-source project. Multiple docs sprints, organized by ML GDEs and GDG organizers worldwide, took place for TensorFlow 2.0 around June 1, 2019.
Whether you are a beginner or an expert in ML or TensorFlow, joining a TensorFlow 2.0 Global Docs Sprint is a great way to get started with contributing to open-source projects, and you will learn a lot while contributing.
This is a step-by-step guide on how to review TensorFlow 2.0 documentation by going through a checklist for each API symbol, report issues found, and optionally create a Pull Request (PR) to fix the issues. It can be used as a cheatsheet whether you are attending a Docs Sprint event near you, or while following along on your own.
High level summary of the steps:
Be sure to read how to Contribute to the TensorFlow Documentation on tensorflow.org for more details. If you run into questions, please post them to the TensorFlow Docs Gitter chat room. Use hashtag #TFDocsSprint when posting on social media.
1. Decide which API symbol to review
- Take a look at the TensorFlow Docs Task List here.
- Choose a symbol that you are interested in working on. Don’t choose it if someone else is already working on it — look at the Owner’s GitHub Handle’s cell to make sure that no one else is working on it.
- Write down your GitHub handle as the owner and indicates that you are reviewing this symbol. This is to avoid duplicate work by someone else. You add it to the sheet as a comment.
2. Review the documentation
For each symbol, you will need to review the documentation against the code. If there is a link in the symbol documentation, take tf.lite.TFLiteConverter as an example, click on that link (“ Defined in
lite/python/lite.py”)to see the code as well as the Python docstring.
Review the symbol and assess the doc quality using the checklist in the TF 2.0 API Docs FAQ here. Note any issues such as missing links, incorrect description and missing information etc.
3. Report the review result
After you review the symbol, please report the results in the task list and report issues on GitHub if applicable:
- Enter your review results (as comments) in the TensorFlow Docs Tasks here. Once Paige accept your comments in the task sheet, your updates will be reflected.
- Open a new docs issue on Github to report any issues you found. Include the Github link in the docs task sheet. Note the issue already has the checklist pre-populated. ← see issue 25844 as an example. Make sure to prefix your issue title with [TF 2.0 API Docs].
Protip: If you’d like to fix the doc issue, answer “Yes” to the question “Submit a pull request?”; otherwise “no” in the new GitHub doc issue you are opening.
4. (Optional) Fix the doc issues
This is totally optional - if you would like to fix the doc issues yourself, you can update the docstring, and create a PR. Note: please include the link to PR in the GitHub doc issue you opened.
First you need to location the source file to edit. As mentioned above, you can find the source file from the link in each of he API documentation. (Note: you can’t find the file then just report the issue in the task list with a comment).
Once you are on the GitHub file that you would like update, you can use GitHub’s web-based file editor for making simple changes. Paige Bailey made a nice short video on this:
- Switch to Edit mode — on Github click on the edit pencil icon “Edit the file in your fork of this project”