Restructure Kubeflow Docs: Applications and Bundles

[jlewi]

Our installation instructions have a very complicated flow symbolized by the diagram on this page.
https://www.kubeflow.org/docs/started/getting-started/

Can we simplify this and just have the table listed below that lists the different bundles for Kubeflow?
https://www.kubeflow.org/docs/started/getting-started/#deployment-quick-reference

Going forward I think we should present people two options

1. Install a bundle of Kubeflow applications using one of the distributions of Kubeflow

   • Is bundle a better name then distribution?

2. Install individual applications

   • Applications can provide standalone installation instructions and we can direct people to them.

Listing the compatible Kubernetes distribution should then be the responsibility of the bundle and the individual applications; i.e. each set of docs should specify requirements maintained by the bundle or application owners respectively. This would help address issues with #2264.

[issue-label-bot]

Issue-Label Bot is automatically applying the labels:

Label	Probability
area/docs	1.00
kind/feature	0.86

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

[jlewi]

@8bitmp3 and @joeliedtke What might the Kubeflow doc structure look like if we were to organize the docs around applications and bundles?

[jlewi]

Right now we have the section "Kubeflow Components" but some applications like "Jupyter" and "Pipelines" are not subsections of those sections.

Should we reorganize all the docs about distributions under a single section? Right now they are split

• Most of the "Kubeflow On ... " are top level sections
• Getting Started has subsections e.g. Kubernetes installation that should probably be moved into bundles

[8bitmp3]

Thanks for bringing this up @jlewi .

Just remembered my post in the KF v1.1 discussion #1984 (comment), so sharing it here.

cc @RFMVasconcelos @Bobgy

It may be a bit dated since the team has made some good improvements:

@jlewi regarding streamlining Kubeflow's Getting Started section

I think it was @LyleHenkeman who posted about it here. ... the current guide is a bit "busy".

I think it's about reducing cognitive overhead.

...

1. Consistency in naming 🔀

In Getting Started, we are greeted with a nice flow chart/diagram (see below) before receiving instructions on what to do next in each of the three installation paths (in green) that cover four potential scenarios.

(I copy-pasted sections - they are in orange and green - from the entire site's Getting Started view to find the corresponding guide per each solution (blue).)

In addition, there're links in the menu to the left for each of three installation guides (in orange). And on the right-hand side, there are Docsy-generated (?) subheadings from the "Installing Kubeflow" markdown file:

Because the same things are reworded in different ways, including in the flow chart, this can be a bit confusing, especially for those new to K8s and KF, since you're greeted with all that when you try to figure out how to install.

Descriptions/titles of each of our three installations can be more consistent, so the whole thing is more friendly for the newcomers.

I think this is a small but a significant example of cognitive overload.

2. Installation steps for KF on an existing cluster 🔀

Related to @LyleHenkeman's post here.

Notice the flow below.

1. You're in Installing Kubeflow and come across Installing Kubeflow on an existing Kubernetes cluster. Click on the guide to deploying Kubeflow on Kubernetes:

2. This takes you to an Overview of Deployment on Existing Clusters

3. You have to scroll down and inside the last table are the next options (click on one of them):

4. To run KF on K8s with Istio, select Follow instructions: Kubeflow Deployment with kfctl_k8s_istio, which has its own Before you start and other sections.

Note that in Step 4 you should be using kfctl. I assume that the user should have read Installing command line tools back on the Getting Started page.

[rui-vas]

Hi @jlewi @8bitmp3, thanks for bringing this topic again!

I think we all agree that there is space to improve there. In PR #2261 we already removed some redundant things and we kind of agreed that this install page should be a gateway mostly with links to actual docs, which would make it version agnostic (always up to date not to drive users away).

I like the full-bundle options + apps install methods. We could start by focusing on the first, as we don't have yet docs on single app installs.

I think restructuring the docs tree makes sense - we could have a structure doc like this one where we agree on the steps forward. (I can lay the structure on this one and you can port it to an official one :) )

WDYT?

[jlewi]

@joeliedtke thoughts?

[jlewi]

@RFMVasconcelos I think a doc structure like the doc is a good one.

My suggestion would be to turn this into a proposal; i.e. use a PR instead of a doc.
So open a PR here
https://github.com/kubeflow/community/tree/master/proposals

with ideas for the suggested layout using markdown.

[rui-vas]

That's a great point ;) Easier to iterate on. Will create by EOW.

[8bitmp3]

That looks good, thank you @jlewi @RFMVasconcelos

[jlewi]

Do we also want to consider breaking up the docs into multiple web sites?

Right now the website is monolithic. I think this is becoming problematic from a release perspective. Each WG is free to release their applications on their own release schedule. This will cause problems with the docs because they can only be released monolithically.

If each application has its own site; e.g.

pipelines.kubeflow.org
notebooks.kubeflow.org

Then each WG could be in charge of its own docs website and control its own releases.

www.kubeflow.org could then become just top level navigation.

What do the various WG leads think?

@kubeflow/wg-automl-leads
@kubeflow/wg-notebook-leads
@kubeflow/wg-pipeline-leads
@kubeflow/wg-training-leads
@kubeflow/wg-serving-leads

[Bobgy]

+1 to breaking up the website

I think another benefit is that we can move pipeline related documentation to kubeflow/pipelines repo, so a feature can be implemented with its documentation in one PR.

[8bitmp3]

@jlewi @Bobgy @RFMVasconcelos

+1 for making it more modular. Decoupling each component to make deployment easier. I think I read about this somewhere 😃

[terrytangyuan]

+1 to break up the website as long as each WG won't have to spend too much time setting up skeleton/infrastructure, etc. They should be able to focus on the content of the website instead, e.g. writing markdown files.

[rui-vas]

+1, that makes sense if releases will be also app-centric. I'll reflect that in the PR.

[andreyvelich]

+1 to make this change and move website docs under /kubeflow/<component> repo as @Bobgy mentioned before.

Two questions.

1. How we can deal with multi-projects WG ? For example, Training WG includes several repositories for each operator.
2. Who will be responsible to make each WG website in the same style to make navigation and UX very clear/easy for the user?

[joeliedtke]

I like the idea of letting each working group release on their own schedule. My main concern is that this could make it more difficult for users, especially users who depend on several Kubeflow applications.

From a maintenance standpoint, does this require us to duplicate content? For example, running a Kubeflow application in different environments (cloud providers, local Kubernetes clusters) will have different authentication and authorization steps. Does it seem likely that this would need to be in several repositories?

[rui-vas]

As promised I started a proposal, which now contains only the current docs structure. Might then be a good space for comments on how to improve.

cc @jlewi @8bitmp3 @joeliedtke @Bobgy

[cvenets]

I like the idea of letting each working group release on their own schedule. My main concern is that this could make it more difficult for users, especially users who depend on several Kubeflow applications.

I agree with @joeliedtke on this. I think that when restructuring the website we should be thinking about the users first, even though I understand that fragmenting/segmenting makes it easier for the contributors and for maintenance.

Especially, if someone uses more than one Kubeflow app, it will be very difficult to navigate a segmented website. Even if we want to have specific parts of the website being maintained by WGs, I think we should have a generic part under kubeflow.org which will provide the overview, help novice users understand the whole concept, and then help them navigate to either a vendors/distro list, or to specific components to learn more or install them standalone.

[joeliedtke]

Are there any suggestions for OSS projects that have separate sites for sub-applications that we think work really well? I think that it would be helpful to take a look at those sites to better understand how those projects are solving this problem.

[thesuperzapper]

I agree with the breaking up the docs, but... it only makes sense to seperate the docs for components which meet two criteria:

1. The sub-app must actually make sense on its own, without the rest of Kubeflow
   • And because most Kubeflow components depend on some cluster-level stuff (e.g. Istio), how will this be dealt with in the new doc structure?
2. The sub-app must actually have a release version which is independant of Kubeflow itself
   • For example, what about CentralDashboard, (which is owned by Notebooks now I guess)?

[jlewi]

My main concern is that this could make it more difficult for users, especially users who depend on several Kubeflow applications.

Kubeflow is not a closed system. The AI landscape is growing and my expectation is the vast majority of applications that users will consume as part of their AI platform will be developed outside of Kubeflow; e.g pachyderm, feast, Ludwig, nuclio, etc...

From Day 0, Kubeflow has shipped applications outside Kubeflow; e.g. Argo, Seldon etc... We have always been upfront that being developed under Kubeflow was not a requirement to integrating with Kubeflow.

So standalone docs for each application seems like a natural progression.

Consistent styling is the least of my worries at this point. Docs are inconsistent and not updated on any regular basis.

@8bitmp3 and @RFMVasconcelos have done a great job(#2177) wrangling various application owners to update their docs but this doesn't look sustainable at all.

I think we need to move to a more standalone and independent set of docs in order to ensure that one or more WGs not keeping up doesn't negatively impact KF as a whole.

Towards this end, I think different styling is actually a good thing as it helps convey to users the independence of these projects. KFserving, Training Operators, Notebooks, Pipelines, AutoML; These are all at best loosely coupled and capable of being used independently. There's no reason why the failure of one of these WGs to adequately maintain their docs should reflect on the other WGs.

[amygdala]

+1 to breaking up the website

I think another benefit is that we can move pipeline related documentation to kubeflow/pipelines repo, so a feature can be implemented with its documentation in one PR.

+1, this is a good point that moving pipeline docs to its repo would probably simplify things.

[jlewi]

I think we should aim to have separate websites for each application in Kubeflow 1.3.

@yanniszark since you will be driving the 1.3 release WDYT?

[yanniszark]

@jlewi I think that the docs definitely need re-factoring. I understand the arguments of being able to update independently, but even if we want to have documentation that is component-specific and updated independently, we still need to have an overarching structure to help users navigate the docs.

Thus, I think that the ideal is somewhere in the middle. We should have at least a few pages under kubeflow.org that let people understand what Kubeflow is and why it was conceived. And then maybe guide the users to either specific components (with their docs) or to a list of distros/clouds (with their docs). The current structure definitely doesn't help, and this is why it is so difficult to maintain and consume.

We discussed this internally, and we decided to put some cycles in the docs for 1.3 to help Rui, who is doing some heavy lifting in this area. So, let us have a good look at the whole content, which we haven't done until now, and we will be back with a specific proposal for the community to review, as part of the 1.3 release.

[thesuperzapper]

There is currently a proposed structure change for the website in PR: kubeflow/community#440

What are peoples thoughts about this, should we?

1. make the changes from Restructuring Kubeflow docs proposal community#440 first, and then to start the process of separating out the component docs
2. start the process of splitting up the docs, and not worry about Restructuring Kubeflow docs proposal community#440

[rui-vas]

Hi @yanniszark, thank you for the offer to help out in docs!

• I have started this PR really as an open proposal and a few people in the community have already proposed changes in this PR. It would be great if we could get community consensus there, not having 2 versions.
• If you could help on this front, where I am struggling the most atm is screening issues to identify in-page improvements and problems and correct them.

Hi @thesuperzapper, IMO separation and structure are somewhat independent. If we agree that a good structure for Pipelines is A > B > X > Z, then we can represent that in a section or separate domain. Does that sound like a good way to go?

I admit that this proposal has taken a bit of time to wrap, apologies on my end!

I think the best option to avoid more time of inaction on this front may be:

1. Committing changes according to current comments in the PR
2. Remove WIP
3. Send an email to kubeflow-discuss to that we can have more active participation in the discussions
4. Discuss the proposal in the next community meeting - Dec 8th.

I can have points 1-3 done this weekend 🚀

[stale]

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.