Improvements for Kubeflow Pipelines documentation

[hbelmiro]

• Review the structure of the docs to reflect Kubeflow 1.9 #3716
• Remove deprecated KFP "Lists of artifacts" warning #3760
• Add content to the Kubeflow Pipelines V2 installation page #3714
• Improve KFP backend and installation instructions #3729
• Document that is possible to upload a .zip or .tar.gz file as a pipeline #3715
• Incorrect links in V2 / data types / artifacts documentation page #3766

Issues found during #3737

• Fix 404s in _redirects #3761
• Fix broken links to /docs/components/pipelines/sdk-v2 and its children. #3756
• Add "Out of date" warnings to all Pipelines v1 docs #3751
• Move /pipelines/legacy-v1/overview/multi-user/ -> /pipelines/operator-guides/multi-user/ #3749
• Update the Pipelines "Getting Started" page with links to other basic guides #3773
• Add a warning at the top of all Pipelines pages in the Legacy (v1) section about v2 #3764
• Move (and update) Pipelines pages from Legacy (v1) to Pipelines root #3750
• Create a V2 version of "Manipulate Kubernetes Resources as Part of a Pipeline" #3752
• Update the "Pipeline Root" concept page and add a new "Configure Pipeline Root" page under "Operator Guide" #3757
• Create a feature map to understand what are the features that need documentation #3742
• Rethink the "Build a More Advanced ML Pipeline" guide #3741

[StefanoFioravanzo]

@hbelmiro can you please elaborate on the third bullet? Do you have something specific in mind?

[hbelmiro]

@hbelmiro can you please elaborate on the third bullet? Do you have something specific in mind?

@StefanoFioravanzo Done.

[StefanoFioravanzo]

@hbelmiro @diegolovison Hey, I'd like to draw your attention to these two comments:

• Improve docs for Training Operator 1.8 training-operator#1998 (comment)
• Documentation Improvements for Katib 0.17 katib#2314 (comment)

and then the Katib PR that addresses those comments:

• Katib: Reorganized Katib Docs #3723

As you can see, I am proposing a restructuring based on principles that we can apply for KFP as well. Would either one of you take the lead and propose a similar restructuring for the KFP docs? It would be great to start with a proposal similar to what I did for Katib, outlining what needs to change, what needs to move, what new sections we need. As you go through this exercise, you can also take note of what user guides or topics are missing, and share a separate list of TODOs.

We can track this here #3716 if you want. Whatever suits you better. Let me know your thoughts!

PS: My thought process follows this doc framework https://diataxis.fr/ - I encourage you to take ~1h and go through it. It's very well written and easy to follow. It won't take long!

[hbelmiro]

@StefanoFioravanzo I really like the idea. It will enhance the documentation's quality and keep consistency between the components. We could also mention that structure in https://www.kubeflow.org/docs/about/style-guide/.

Would either one of you take the lead and propose a similar restructuring for the KFP docs?

Yes, I can do it.

We can track this here #3716 if you want. Whatever suits you better. Let me know your thoughts!

Yeah, sounds good.

[StefanoFioravanzo]

@hbelmiro Can you link this in the first comment? #3729

[hbelmiro]

@StefanoFioravanzo I added as a new bullet since it can be done in a follow-up PR.

[hbelmiro]

/area pipelines

[thesuperzapper]

We should also update the link in the Legacy (v1) / References / Pipelines SDK Reference to actually point to the V1 version of the SDK, it currently points to:

• https://kubeflow-pipelines.readthedocs.io/en/stable/

It should be updated to point to the last V1 version:

• https://kubeflow-pipelines.readthedocs.io/en/1.8.22/

[thesuperzapper]

We should place a warning at the top of all pages in the Legacy (v1) section that says something like:

This page is for Kubeflow Pipelines V1.
While the V2 backend is [backwards compatible](xxx_v1_v2_compatibility_xxxx) with V1 pipelines, 
we recommend you [upgrade to the V2 SDK](xxxx_v2_migration_guide_xxxx), please see the [V2 docs](xxxx_v2_docs_xxxx) for more information.

The xxx_v1_v2_compatibility_xxxx page can probably be the References / Version Compatibility page, but it needs to be made clearer and brought up to date for the 2.1 and 2.2 releases.

[varodrig]

@hbelmiro
@StefanoFioravanzo
@rimolive
should we close this issue since it's related to Release 1.9 or is this still a working progress?