[Kubeflow Community Meeting] Automate everything, even documentation! docs that are "self-testable" and OWNER files that replicate?

[ricoms]

From Kubeflow Community Call Meeting 2020-08-04

From the participants of the meeting, it raised a couple of "experimental" and possible solutions to documentation issues:

• 1st The goal would be to create self-testable documentation. Basically the document should contain code that complements the raw comments or text, and that code is automatically run (ci/cd) and tested before merging to the documentation website.
• 2nd It was raised some difficulties on having PRs approved in some fields and this was pointed about to be from modules that had no clear OWNERs. Some suggestions were brought up but one that stuck with me is to evaluate the possibility of automating OWNERs files from source code repositories to sync correctly with the website repository. The goal would be to facilitate identifying who are the OWNERS of specific modules.

I consider this issue as the beginning of building a possible "clear asks" (by David Aronchick:) for this subject and maybe build up from here an initial documentation work-group with some clear feature goals? Also, as Josh Bottum raised, would it be plausible/needed to hire someone full-time for this or a work-group would suffice?

[issue-label-bot[bot]]

Issue-Label Bot is automatically applying the labels:

Label	Probability
area/docs	0.96
kind/feature	0.57

Please mark this comment with :thumbsup: or :thumbsdown: to give our bot feedback! Links: app homepage, dashboard and code for this bot.

[jlewi]

Might be worth looking at fastpages. https://github.com/fastai/fastpages

Fast pages allow you to turn notebooks into pretty web pages. You can then build CI around the notebooks.

[8bitmp3]

Thanks for sharing @ricoms. We're all in different time zones and this really helps.

self-testable documentation

[fastai] Fast pages allow you to turn notebooks into pretty web pages. You can then build CI around the notebooks.

• The TensorFlow docs team has a customizable nblint linter for Jupyter notebooks (cc @lamberta)
• Linters for Markdown (e.g. Vale and several others) can help authors and reviewers and reduce time spent on a PR - integrating one of them in CI/CD on kubeflow/website would be excellent
• Tools from software engineering can be implemented for docs - docs are [human] code (this goes as far back as 2015, 2015, and 2017)

Example: At Mapbox "To keep our work accurate and unified under a common voice... we implemented an automated content testing system (fully open source!) to do some of the work for us. Automated tests have helped us embed quality writing and editing into the development process as much as code testing does" (source: writethedocs)

If @jlewi and the community are happy, we can start exploring the best practices and start implementing them here. I can ask the tech writing community for tips and gather as much information as possible.

to facilitate identifying who are the OWNERS of specific modules

Yes, I (@8bitmp3) and @RFMVasconcelos are on it: https://github.com/kubeflow/website/issues/2109 and https://github.com/kubeflow/website/issues/2108 (by @jlewi )

[lamberta]

Hi @8bitmp3 and all,

Yes, most technical docs on tensorflow.org are notebooks. These are tested when we generate the site and link off to Colab for users to run the notebook, for example: https://www.tensorflow.org/tutorials/quickstart/beginner [source notebook in GitHub].

We use nbfmt and nblint for consistency: https://github.com/tensorflow/docs/tree/master/tools/tensorflow_docs/tools —and added them to the CI for pull requests. You're welcome to take a look at some of our GitHub Actions workflows.

The notebooks are executed in an internal VM. You might be able to set up something similar using nbconvert (or another tool) in GitHub Actions, but quota might be an issue, at least on long-running notebooks.

Happy to chat about our experience using notebooks-as-docs. Best, Billy

[issue-label-bot[bot]]

Issue-Label Bot is automatically applying the labels:

Label	Probability
area/jupyter	0.51

Please mark this comment with :thumbsup: or :thumbsdown: to give our bot feedback! Links: app homepage, dashboard and code for this bot.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.