search

kubeflow / website

Kubeflow's public website
Creative Commons Attribution 4.0 International
145 stars 750 forks source link

Improvements for Kubeflow Pipelines documentation #3712

Open hbelmiro opened 2 months ago

hbelmiro commented 2 months ago

Issues found during https://github.com/kubeflow/website/pull/3737

StefanoFioravanzo commented 2 months ago

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

hbelmiro commented 2 months ago

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

@StefanoFioravanzo Done.

StefanoFioravanzo commented 1 month ago

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

and then the Katib PR that addresses those comments:

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 https://github.com/kubeflow/website/issues/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 commented 1 month ago

@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 https://github.com/kubeflow/website/issues/3716 if you want. Whatever suits you better. Let me know your thoughts!

Yeah, sounds good.

StefanoFioravanzo commented 1 month ago

@hbelmiro Can you link this in the first comment? https://github.com/kubeflow/website/issues/3729

hbelmiro commented 1 month ago

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

hbelmiro commented 2 weeks ago

/area pipelines

thesuperzapper commented 2 weeks ago

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:

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

thesuperzapper commented 2 weeks ago

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.