search

kubeflow / website

Kubeflow Website
https://www.kubeflow.org
Creative Commons Attribution 4.0 International
150 stars 777 forks source link

update the "notebooks" component docs for 1.3 #2637

Closed thesuperzapper closed 2 years ago

thesuperzapper commented 3 years ago

With the significant number of changes made in Kubeflow 1.3 to the "Kubeflow Notebooks" component, we should probably effectively rewrite the docs for it, or at least update them.

thesuperzapper commented 3 years ago

@kubeflow/wg-notebooks-leads whats our plan for this?

thesuperzapper commented 3 years ago

@DavidSpek is probably interested too.

thesuperzapper commented 3 years ago

/priority p2

davidspek commented 3 years ago

Explaining how to set logos/icons for the UI and the new way notebook resource requests and limits work (with the new limitFactor options) should definitely be added. The section about creating notebook images also needs an overhaul so it matches with the new Dockerfiles/images.

rui-vas commented 3 years ago

+1! Thanks for starting this @thesuperzapper

thesuperzapper commented 3 years ago

I think we start by agreeing on the page structure, e.g. what pages will we have, and what will their headings be.

kimwnasptd commented 3 years ago

I think we start by agreeing on the page structure, e.g. what pages will we have, and what will their headings be.

Yeap, this is a good first step, especially now that we've extended both the Notebooks controller and spawner web app for allowing users to launch RStudio and VSCode instances as well.

I was thinking of keeping the Jupyter Notebooks as the prominent Notebooks component, so we keep titles like Overview of Jupyter Notebooks in Kubeflow, but also add a section there like Other Notebooks and IDEs and document there as well how a user could launch an RStudio/VSCode instance.

@kubeflow/wg-notebooks-leads @DavidSpek WDYT?

davidspek commented 3 years ago

Here too there is a problem with mentioning VS Code and RStudio by name, which will make the docs surrounding this a bit more difficult to write as things need to be kept general but still be easy to follow.

The Create a Custom Jupyter Image would become more general (Creating a Custom Notebook Image) and need to be updated for the new notebook images.

Set Up Your Notebooks is a pretty bad name as it can be interpreted as many different things. I believe a slightly modified version of the current subtitle would be better: Getting started with Notebooks on Kubeflow or Getting started with Notebook Servers on Kubeflow.

The Overview of Jupyter Notebooks in Kubeflow doesn't really contain a lot of information, and doesn't contain any information that is related to Jupyter specifically. So I'm not sure it makes much sense to have this be a the main overview section. I don't necessarily disagree with keeping Jupyter as the most prominent IDE, but I don't think the section title for a page with information not related to Jupyter is the place to do it. How to keep Jupyter as the most prominent IDE in the docs will depend on the other sections.

Related to the previous paragraph, the Volumes Web App and Tensorboards Web App are now missing from the docs. Should those get a separate entry under Components or should the Notebook Servers entry be changed to something more general so the VWA and TWA can be included under it? Personally, I think both options could work well with a good implementation.

thesuperzapper commented 3 years ago

We should make sure to point users to the "Example Notebook Servers" docs about making custom notebook images, as some users don't seem to be finding that README.

davidspek commented 3 years ago

/area docs

thesuperzapper commented 3 years ago

I have raised a PR which partially addresses this: https://github.com/kubeflow/website/pull/3003

thesuperzapper commented 2 years ago

This issue was addressed by: https://github.com/kubeflow/website/pull/3003