Closed ricoms closed 3 years ago
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.
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.
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.
nblint
linter for Jupyter notebooks (cc @lamberta)kubeflow/website
would be excellentExample: 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 )
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 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.
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.
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:
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?