Proposal: Remove and Reorg Knowledge Base

[plumbis]

Background

Since the docs reorg in #271 we've had a Knowledge Base section that has been a bit of a catch-all for docs that don't fit into the existing user docs.

Some of this content is older and needs to be revised or removed and some of it is newer, popular content.

@jbw976 also raised two good points in #473 that the KB makes the left-hand navigation dynamic and confusing and that the "Configuration Guides" is a catch-all.

Current Status

The KB currently has 16 pages, sorted here by views in the last 90 days:

1. Configuring Crossplane with Argo CD (3058 views)
2. Import Existing Resources (2697 views)
3. Troubleshoot (2484 views)
4. Understanding Connection Details (2134 views)
5. Write a Composition Function in Go (1981 views)
6. Multi-Tenant Crossplane (1844 views)
7. Write a Composition Function in Python (1637 views)
8. Vault as an External Secret Store (1474 views)
9. Vault Credential Injection (918 views)
10. Disaster Recovery with Crossplane (858 views)
11. Composition Revision Example (833 views)
12. Composition Revisions (767 views)
13. Feature Lifecycle (406 views)
14. Self-Signed CA Certs (386 views)
15. Release Cycle (285 views)
16. Learn More (239 views)

Proposal

My proposal is to

1. Delete the existing /knowledge-base directory. All existing URLs will have redirects to their new locations.
2. Move Composition Revisions, Composition Revision Example and Understanding Connection Details to the existing Concepts section.
3. Create a new "Guides" section that would cover 3rd party integrations or more specific Crossplane examples. This section would contain Configuring Crossplane with Argo CD, Write a Composition Function in Go, Multi-Tenant Crossplane, Import Existing Resources, Vault as an External Secret Store, Vault Credential Injection, Disaster Recovery with Crossplane, Troubleshoot, Self-Signed CA Certs
4. Create a new Learn section that would provide information about Crossplane and curated links to external resources. This would contain Learn More (239 views), Release Cycle (285 views) andFeature Lifecycle.

This doesn't need to be done as a single PR but can be broken up on a per-page or per-section basis. For example, moving pages to Concepts can be on a per-page while the "Learn" section may make more sense as a single action.

[jbw976]

This looks reasonable to me @plumbis!

A few thoughts:

• I appreciate the attention to creating redirects for all moved pages, so we can avoid old links out there in the wild and search engine results
  • actually, we can do an removal of the /knowledge-base path in google search when we're ready to, so just let me know when we can do that
• With /knowledge-base being removed completely, does this mean the left navigation pane will be able to stay completely static as the user navigates to different pages? the dynamic changing of nav pane entires has continuously been jarring for me, so removing that from the experience would be awesome!
• I've often thought the Troubleshooting page wasn't a good fit for its current "Configuration Guides" section. Sounds like you'll still keep it in a "Guides" section here. But I think i'm good with that as long as its called "Guides" and not "Configuration Guides". Perhaps the "Configuration" part of the section title was what felt the most misleading to me 😉

[plumbis]

@jbw976 -

does this mean the left navigation pane will be able to stay completely static

Yes! Here is a very rough demo https://deploy-preview-753--crossplane.netlify.app/

This is only to show the nav updates. I haven't addressed any ordering, section titles or anything like that.

Sounds like you'll still keep it in a "Guides"

I struggled with this and I'm open to suggestions. I don't want to create sections with only 1 or 2 pages so I avoided having unique "Operations" and "Integrations" section and thought that "Guide" may be a good enough generic.

[jbw976]

Yesss, I love the more static navigation panel now @plumbis!! It's changes only if you go to the docs contributing section, but that is totally fine since that area really is more segregated than the rest of the content in user docs and KB. Having those two together in a static navigation is the most important part. Looks like the right path to me! 🙇‍♂️

[jbw976]

I think this was fixed in #755 - KB is removed! 🪦