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

Review the structure of the docs to reflect Kubeflow 1.9 #3716

Closed
Tracked by #3712
hbelmiro opened this issue Apr 18, 2024 · 11 comments · Fixed by #3737
Closed
Tracked by #3712

Review the structure of the docs to reflect Kubeflow 1.9 #3716

hbelmiro opened this issue Apr 18, 2024 · 11 comments · Fixed by #3737
Assignees

Comments

@hbelmiro
Copy link
Contributor

hbelmiro commented Apr 18, 2024

Based on #3712 (comment), we need to review the structure of the docs.

The new structured is defined in the comment bellow.

@hbelmiro
Copy link
Contributor Author

hbelmiro commented May 8, 2024

/assign @hbelmiro

@StefanoFioravanzo
Copy link
Member

@hbelmiro this looks pretty good! Are you planning on submitting a PR with this refactoring? Few questions:

  • Did you take every single guide from the current structure, or is there anything that was left out?
  • Current we have v1 and v2 as the two top-level sections. Are you planning to remove them? If yes, where does the v1 content go?
  • It could make sense to promote Migrate from KFP SDK v1 to a top-level page. WDYT?

@hbelmiro
Copy link
Contributor Author

@StefanoFioravanzo

Are you planning on submitting a PR with this refactoring?

Yes, once we get aligned with the structure.
I plan to move the existing pages to the new structure in a first PR and then make other changes, if needed, in follow-up PRs. It will make reviews easier and unlock other changes.

Current we have v1 and v2 as the two top-level sections. Are you planning to remove them? If yes, where does the v1 content go?

Actually, not. I didn't analyze v1. The suggested structure is only for v2.
What do you think of setting v1 as a stretch goal? We can prioritize v2 and when v2 is good we enhance v1.

It could make sense to promote Migrate from KFP SDK v1 to a top-level page. WDYT?

It could, but I don't see the need. Also, it concerns me that we can be opening a precedent and having everything mixed again in the future.

@StefanoFioravanzo
Copy link
Member

StefanoFioravanzo commented May 13, 2024

I plan to move the existing pages to the new structure in a first PR and then make other changes, if needed, in follow-up PRs. It will make reviews easier and unlock other changes.

Totally agree!

What do you think of setting v1 as a stretch goal? We can prioritize v2 and when v2 is good we enhance v1.

I would rather suggest an approach that moves the docs away from this structure

/pipelines/
  /v1
  /v2

to something like this

/pipelines/
  /<unfolded v2 content>
  /legacy-v1/

But we can work on this in a separate PR. I don't think it makes sense to spend precious hours in refactoring the v1 structure. We can keep it as-is and move it under that legacy section. If needed we can promote some guides from v1 to v2.

It could, but I don't see the need. Also, it concerns me that we can be opening a precedent and having everything mixed again in the future.

It's a very good point. I was just wondering if that was a good place. It is a "user guide", although not exactly a "how-to". But it's ok, we can refine in the future if the "user guide" section needs more splitting.

@hbelmiro
Copy link
Contributor Author

hbelmiro commented May 13, 2024

I would rather suggest an approach that moves the docs away from this structure

/pipelines/
  /v1
  /v2

to something like this

/pipelines/
  /<unfolded v2 content>
  /legacy-v1/

But we can work on this in a separate PR. I don't think it makes sense to spend precious hours in refactoring the v1 structure. We can keep it as-is and move it under that legacy section. If needed we can promote some guides from v1 to v2.

Perfect. I think the same way.

It would be nice to have @milosjava's inputs also on the new structure.

Updated structure

@hbelmiro
Copy link
Contributor Author

Also including @diegolovison in the discussion.

@milosjava
Copy link
Member

@hbelmiro documentation is quite good. One thing maybe to improve would be to give more info in section control-flow , regarding the part when it says: " not yet supported by the KFP orchestration backend, but may be supported by other orchestration backends". Do we have some docs regarding "orchestration backends"?

@hbelmiro hbelmiro changed the title Review the structure of the docs and the not-implemented feature notes to reflect Kubeflow 1.9 Review the structure of the docs to reflect Kubeflow 1.9 May 20, 2024
@HumairAK
Copy link
Contributor

cc @chensun / @zijianjoy

@HumairAK
Copy link
Contributor

HumairAK commented May 27, 2024

In my experience, Operational and User driven docs are separated into their own sections

Currently the docs do not separate these personas, and we should really start doing that, a user of kubeflow may not care about how to install kubeflow, or how to configure object storage, minio, aws, etc. where as operations will

I suggest making a few adjustments like so:

* Overview
  *  Introduction
  *  Getting Started
* Operator Manual
  * Installation
  * Server Configuration
* User Guides
  * ...same as before (except server configuration moved to operations)

There's a lot that can added to this section moving forward to make managing kubeflow pipeline deployments easier

@hbelmiro
Copy link
Contributor Author

/area pipelines

hbelmiro added a commit to hbelmiro/issues-i-can-help-you-with that referenced this issue Jun 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants