Refactor the Kubeflow getting-started section

[sarahmaddox]

Restructure the entries into groups:

• Cloud
• Local
• On prem

[issue-label-bot]

Issue-Label Bot is automatically applying the label improvement/enhancement to this issue, with a confidence of 0.74. Please mark this comment with 👍 or 👎 to give our bot feedback!

Links: app homepage, dashboard and code for this bot.

[sarahmaddox]

/assign @dansanche

[k8s-ci-robot]

@sarahmaddox: GitHub didn't allow me to assign the following users: DanSanche.

Note that only kubeflow members, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

/assign @dansanche

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[daniel-sanche]

I opened a PR addressing this, but we couldn't get consensus on how to organize this section, so I'm closing it and hoping we can use this bug to discuss how to improve the Getting Started experience.

I think creating a clear path for new users through the Getting Started guide should be a top priority. As it stands, the number of docs in the getting started docs is overwhelming and hard to navigate, and it seems like there are more docs coming as every platform wants to be represented in this section.

I see two options to improve this:

option 1. use folders to split up the guides into buckets, so new users can focus only on the use-case that matters to them. This was what I tried to implement, but it's difficult to categorize all existing docs in a way that is clear and makes all stakeholders happy.

option 2. create a single getting started guide based on a standard open platform like minikube that we can direct all new users through. This option would be ideal if we could provide a great experience, but I haven't had much luck getting Kubeflow set up locally, so I don't know how feasible this is.

Let me know your thoughts

[kbhawkey]

I agree with both points, especially the second point. I think the Getting Started guide could include a section that provides a clear way to "try out" Kubeflow, locally -- which may or may not be different from running Kubeflow On-prem datacenter. Also the instructions could explain 1) what/how to install 2) what/how to deploy 3) what samples are available to test/evaluate 4) what to do next.
Is there any interest in setting up a Kubeflow "lite" installation. It seems like the installation, at this point, contains all components.

[carmine]

I'm curious if things fall along the lines of "Installers", "Appliances" and "Managed", or something like that. For instance, with kubernetes, I think you'd characterize GKE, AKS, EKS as managed kubernetes offerings, and things like kubeadm or charmed kubernetes as installers / distributions.

Agree that a better organization is strongly desired.

I think it starts with either "Where do you want to deploy Kubeflow" or "How do you want to consume Kubeflow". For the latter Question, things break down like this:

• From a cloud provider
• From an installer
  • In a virtual machine
  • In a desktop
  • In a cloud
• From an appliance (ie pre-baked VM)

I don't love it. To stick with previous effort, ie how to get started:

• Single node solution
  • appliance
  • vm
  • desktop
• Multi node solution
  • public cloud
  • kubernetes

Finally, as another option:

• New to kubeflow? Quickstart guides ...
• Ready for kubeflow in production? Installer guides .. (leads to managed kubeflow, all-in-one, etc)

[carmine]

I wonder if a table would be the best way to present options to the user. With a table we could determine what goes on both axis and then provide links to specific solutions.

[mameshini]

I think a table of Kubeflow Providers would be very helpful, as this list will keep growing.

We can list Kubeflow providers in a table with the following intro:
The following production environment solutions table lists the providers and the solutions that they offer.

In the table we can add a column for supported deployment options: GCP, AWS, Azure, on-prem.

[daniel-sanche]

I think you made a good point about separating the Quickstart guides from the Production Installer Guides. These are targeted at very different audiences, and they are currently both under the "Getting Started" header. Maybe we should add a new "Installers" section, and move some pages in there? That would be a good place to include a table

[sarahmaddox]

Pasting a comment from @jlewi on PR #1051 (comment)

I think this PR is a huge improvement; i.e. adding a level to the hierarchy to group solutions.
I'm still uncertain about what the right items under Getting Started should be.

I'm totally ok with going with the sections in this PR and then continuing to iterate in the future.

The question that comes to mind for the different subsections (e.g. Cloud vs. workstations vs. Kubernetes Install) what are the different groups that we want want to convey?

Some things to consider

• Do we want to distinguish between production and non-production/learning environments?

• Do we want to distinguish between turn-key/vendor solutions as opposed to open/vendor neutral solutions

  • See #977 (comment)

• Grouping VM based solutions (e.g MiniKF, MicroK8s, Minikube) by OS seems a little strange to me.

  • It leads to duplication of information (e.g. MiniKF appears on multiple OS pages)
  • As an alternative what if Minikf, MicroK8s, Minikube etc.. each had their own page under workstation install and then in the overview page we had a table that listed all these options and relevant information such as OS supported?
  • Something akin to the table Kubernetes provides: https://kubernetes.io/docs/setup/

I might suggest the following

• Change "Cloud Install" to "Turnkey-solutions" or maybe "Turnkey Cloud and OnPrem solutions"

  • This way we have a place for other turn key solutions from vendors regardless of whether they are cloud based or not

• Change "Kubernetes Install" to "Installing Kubeflow with Deployment Tools"

  • I don't think "Installing..." is great but I think its less confusing then "Kubernetes Install"

[jtfogarty]

/area docs
/priority p2

[sarahmaddox]

We've made a number of changes to the getting-started section since this issue was raised. I'm going to close the issue now. If anyone wants to discuss the new organization of the getting-started section, please raise a new issue.
/close

[k8s-ci-robot]

@sarahmaddox: Closing this issue.

In response to this:

We've made a number of changes to the getting-started section since this issue was raised. I'm going to close the issue now. If anyone wants to discuss the new organization of the getting-started section, please raise a new issue.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.