TensorFlow 2.0 Global Docs Sprint Cheatsheet

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 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 on tensorflow.org for more details. If you run into questions, please post them to the . Use hashtag when posting on social media.

1. Decide which API symbol to review

  • Take a look at the TensorFlow Docs Task List .
  • 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 as an example, click on that link (“ Defined in”)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 . 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 . Once Paige accept your comments in the task sheet, your updates will be reflected.
  • Open a 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 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 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 on this:

  • Switch to Edit mode — on Github click on the edit pencil icon “Edit the file in your fork of this project”
  • Make your changes to the docstring, preview with a and save. Make sure to follow the when making changes.
  • Submit your PR — Add a title and description to your PR, and click on “Commit changes” to create a new PR.

Acknowledgment: many thanks to the review, feedback and contributions by , , , , and the Docs Sprint organizers.

TensorFlow

TensorFlow is an end-to-end open source platform for machine learning.

Margaret Maynard-Reid

Written by

Google Developer Expert for ML | TensorFlow & Android

TensorFlow

TensorFlow is an end-to-end open source platform for machine learning.