crossplane
Update "positioning" in introduction
What's Missing?
https://docs.crossplane.io/v1.11/getting-started/introduction/ has a lot of wording that reflects past messaging of the project. For example it frames Crossplane as an extension, talks about universal control planes etc. I believe this is something carried over from the old docs - e.g. https://github.com/crossplane/crossplane/tree/v1.10.2/docs.
I think we should update this to reflect the more modern "control plane framework" positioning of the project that is reflected elsewhere, for example:
- https://www.crossplane.io
- https://github.com/crossplane/crossplane/blob/master/README.md
- https://github.com/crossplane/crossplane/blob/master/CHARTER.md
To be clear, I don't think we need to hide or ignore the fact that we're an extension to Kubernetes. This is a really useful framing for folks who know Kubernetes and probably how most folks think of us. I just don't think we want to lead with it as the overarching description of what Crossplane is.
Something related that I'd like us to consider is a more "Crossplane first" framing for our documentation. This might be a larger and more complicated undertaking than simply updating the positioning in the introduction. It may warrant a separate tracking issue, but it's closely related enough to this one that I'm using a comment here for now.
If someone comes to our documentation to learn about Crossplane, we're immediately framing it in Kubernetes concepts and terminology. We talk about CRDs, controllers, etc in the opening three paragraphs. We use the word "Kubernetes" almost twice as often as we use the word "Crossplane".
I'd like us to consider framing the introduction to our project more around what problems it solves, and I don't think the real problem being solved is "I want to manage my infrastructure from Kubernetes". (It is a nice property, buy why? What's good about Kubernetes that makes you want to do that?)
I believe getting this right will be challenging - we do want to relate Crossplane to Kubernetes. It's a great way for the large set of folks who know Kubernetes to get a frame of reference for Crossplane. We've also found that when we get too abstract ("it's a control plane framework!") folks find it harder to understand what exactly Crossplane is for.
I could imagine a future where "how Crossplane concepts map to Kubernetes concepts" (e.g. "this is a CRD") was one page in our documentation, and everywhere else we said things like "a provider extends Crossplane with managed resources for your favorite cloud" rather than "a provider extends Kubernetes with CRDs for your favorite cloud".