Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improvements for Kubeflow Pipelines documentation #3712

Open
11 of 17 tasks
Tracked by #3711
hbelmiro opened this issue Apr 12, 2024 · 9 comments
Open
11 of 17 tasks
Tracked by #3711

Improvements for Kubeflow Pipelines documentation #3712

hbelmiro opened this issue Apr 12, 2024 · 9 comments

Comments

@StefanoFioravanzo
Copy link
Member

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

@hbelmiro
Copy link
Contributor Author

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

@StefanoFioravanzo Done.

@StefanoFioravanzo
Copy link
Member

@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 #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
Copy link
Contributor Author

hbelmiro commented May 2, 2024

@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
Copy link
Member

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

@hbelmiro
Copy link
Contributor Author

hbelmiro commented May 3, 2024

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

@hbelmiro
Copy link
Contributor Author

/area pipelines

@thesuperzapper
Copy link
Member

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
Copy link
Member

thesuperzapper commented Jun 13, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: To Do
Development

No branches or pull requests

3 participants