What contributor documentation improvements do you suggest?

TensorFlow General Discussion
, ,
1

The TensorFlow team is doing a pass on the contributor documentation we have on tensorflow/tensorflow, tensorflow/community, and the website.

Based on your experience in contributing to TensorFlow, are there any docs that could use improvements for a better experience? Are there any docs that are missing?

Looking forward to your suggestions!

cc @billy for visibility

5 Likes
2

And also on tensorflow/docs

1 Like
3

In tensorflow/docs, I guess it is better to give an explanation about nbfmt and nblint. They are very useful tools for contributors and are applied automatically for each pull request by GitHub Actions.

4 Likes
4

Thank you, Sugiyama-san. Would you mind sharing your typical contribution workflow? We realize it’s not so easy for contributions to be submitted, and so we appreciate your view on the need for format & lint checks on notebooks. Are there other techniques you use to streamline your contributions? Thanks!

1 Like
5

Off course! I mainly contribute to tensorflow/docs-l10n and made some contribution to other repos (tensorflow/docs, tensorflow/tfx, and tensorflow/tensorboard) on almost same workflow. Followings are my workflow.

Find an issue

  • Run example notebooks in Colab (I mostly use them for my learning)
  • Find unexpected errors
  • (tensorflow/docs-l10n only) Find untranslated notebooks or outdated notebooks
  • Search issues of the repo to check the issue is already reported or not
  • Try to find the cause of the issue to understand it enough to describe

Report an issue

  • Check README.md and CONTRIBUTING.md to find the way to report the issue
  • Take a look at issue templates to find the most suitable one (each repo can have its own rules and templates)
  • Fill the issue template

Fix the issue

  • Fork the repo.
  • Set up my local development environment following instructions in README.md, CONTRIBUTING.md, setup.py, and other resources (if required, I mostly use Colab because )
  • Fix the issue and push it into my cloned repo.
  • Clone it into my local environment.
  • Apply formatter and linter using nbfmt and nblint following this document
  • Push fix commits to my cloned repo

Make a pull request

  • Make a pull request and if I created the issue, link the PR to the issue
  • Pray to pass the CI :pray: (and fix my PR if needed)
  • Pray to merge it :pray:

I think this is a generic workflow to contribute to OSS hosted on GitHub. I guess, for tensorflow/docs-l10n, this PR-based workflow will soon change into gitlocalize based workflow.

3 Likes
6

I’d like to know how I can contribute to documentation on a more meaningful and frequent basis. I’ve read the contribution guidelines which mention looking at the docs tag in the forums, but how is one to decide the priority of someone’s question on the forums? Should I simply pick the highest viewed docs questions and try to ensure the information is added back into the documentation in the proper location? Is there some secret issue tracking with prioritized docs needs that only team members have access to?

Please contact me on how I can more formally help with documentation and what/how to prioritize the team’s needs.