docs nav RFC: move pipes to concepts #20712
Conversation
|
This stack of pull requests is managed by Graphite. Learn more about stacking. |
yuhan
changed the title
yes thats my thinking too. but i dont think we are there today, maybe soon tho. |
|
Do we have a general principle here for moving something from "guide" to "concept"? Just want to have a policy here so we have a rationale going forward. |
yuhan
force-pushed
the
03-25-docs_move_pipes_to_concepts
branch
from
ac9ba79 to
514769c
Compare
yuhan
force-pushed
the
03-25-docs_move_pipes_to_concepts
branch
from
64c65a6 to
765aee2
Compare
My own take is that we started with "guide" because we were unsure of where this would live and we didn't want to introduce yet another "core concept" without any real adoption/PMF (in other words, this would have existed in a notion page if not for testability). Now that we've seen sufficient adoption and interests to adopt, we are confident that this would be a "concept" (a core abstraction) that exists in a long run. So now it makes sense to move it to "concept". cc @erinkcochran87 for general docs guidelines if any. also cc @erinkcochran87 for another quick review pass to make sure my rebase on this old PR doesn't break any recent doc changes. |
There was a problem hiding this comment.
This looks good to me. Tested a bunch of links and redirects and didn't hit any errors, so I think that part is fine.
Do we have a general principle here for moving something from "guide" to "concept"? Just want to have a policy here so we have a rationale going forward.
I agree - this was one of the first things I asked about when we first released Pipes. Maybe we should just have a top-level 'Experimental' section where we put all experimental things until we decide if they're a go or not. It could be:
- Easier for folks to find experimental stuff and try it out
- Easier for us to add / maintain, since we don't have to think too hard about where the content will initially live
This approach can work for most things, but I'd like to have criteria for what gets defined as a core concept versus a product feature. I'm not saying Pipes shouldn't be that, but we have so many concepts and I want us to be selective (and consistent) about what we choose to include.
|
Thanks Erin!
We're going to do an API audit in the core concepts soon. That can be a good opportunity for us to come up with concept vs product guidelines. |
## Summary & Motivation this PR moves pipes pages to Concepts - updates all internal links - updates nav -- open to suggestions to the exact order of the nav - sets up redirects so /guides/dagster-pipes URLs out there would still work ## How I Tested These Changes preview: https://03-25-docs-move-pipes-to-concepts.dagster.dagster-docs.io/concepts/dagster-pipes <img width="327" alt="image" src="https://github.com/dagster-io/dagster/assets/4531914/0090db02-0d2c-43ac-8f91-2728c91430e2">
## Summary & Motivation this PR moves pipes pages to Concepts - updates all internal links - updates nav -- open to suggestions to the exact order of the nav - sets up redirects so /guides/dagster-pipes URLs out there would still work ## How I Tested These Changes preview: https://03-25-docs-move-pipes-to-concepts.dagster.dagster-docs.io/concepts/dagster-pipes <img width="327" alt="image" src="https://github.com/dagster-io/dagster/assets/4531914/0090db02-0d2c-43ac-8f91-2728c91430e2">
Summary & Motivation
this PR moves pipes pages to Concepts
How I Tested These Changes
preview: https://03-25-docs-move-pipes-to-concepts.dagster.dagster-docs.io/concepts/dagster-pipes