docs icon indicating copy to clipboard operation
docs copied to clipboard

Proposal: Remove and Reorg Knowledge Base

Open plumbis opened this issue 2 months ago • 3 comments

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.

plumbis avatar Apr 10 '24 20:04 plumbis