Add a glossary of Rancher-specific terms

martyav commented 1 year ago

Summary: Rancher (and other SUSE projects/products) use some jargon that can be confusing for newbies.

Details:

Kubernetes already has some overhead in the form of jargon ("charts", "pods", etc.)

Rancher and other SUSE projects and products also come with their own jargon. It can sometimes be difficult to tell if something is a general Kubernetes term or if it's specific to Rancher or RKE.

Examples:

Rancher using "project" for, roughly, "namespace" (I realize this is because projects predate namespaces)
RKE 2 using "machine" for "node"

Let's compile a list of our jargon and put it in the docs as a glossary.

The glossary pages we added to the docset include a lot of HTML tags. This note was originally listed on the glossary page files, explaining why:

This page uses HTML definition list tags. dl indicates the start and end of a definition list. dt indicates the defined term, and dd the definition. These will stay in place until we upgrade to Docusaurus 3 and are able to add the remark-definition-list plugin for native Markdown syntax. We are currently blocked as the plugin requires a handler that isn't currently exposed. See https://github.com/facebook/docusaurus/discussions/8743#discussioncomment-6085581 and https://github.com/facebook/docusaurus/pull/9674

More context on this from #1125:

We (@martyav & @sunilarjun) looked into adding a plugin that would provide native Markdown syntax for definition lists. We landed on this page , which has instructions on adding remark-deflist (repo) to your Docusaurus instance, but the instructions didn't seem to work for our config. I tried remark-definition-list (repo), but that didn't work either. While looking for a solution, I ran across this https://github.com/facebook/docusaurus/discussions/8743#discussioncomment-7778521on an https://github.com/facebook/docusaurus/discussions/8743complaining that the instructions for adding Remark plugins needed improvement. It seems that the plugins need a remark-rehype handler to be configured. There was a https://github.com/facebook/docusaurus/pull/9674to add this functionality to the Docusaurus config file, but I don't think it's available yet on Docusaurus 2. We might need to upgrade to Docusaurus 3. In the meantime, the HTML tags are perfectly functional.

martyav commented 7 months ago

List of terms to define

[x] ☰
[x] ⋮
[x] Apps
[x] Apps & Marketplace
[x] Catalogs (section)
[x] Catalogs (Helm chart repos)
[ ] Cloud credentials
[ ] Community (Rancher edition) -> discuss with Cam
[ ] Deployment
[x] Downstream cluster
[x] Extensions
[ ] External auth
[x] Hosted cluster
[x] Imported
[ ] Integrations
[ ] Hosted cluster
[ ] Hosted pools
[x] K3s
[ ] Local auth
[x] Local cluster
[ ] Machine pool
[x] Managed cluster
[ ] Neuvector Prime
[ ] Node template
[ ] Prime
[ ] Project
[ ] Project resource quotas
[ ] PSA
[ ] PSA Config Template
[ ] PSP
[ ] Rancher chart
[ ] Rancher CLI
[x] Rancher Enterprise
[ ] Rancher Kubernetes API (RK-API)
[x] Rancher Kubernetes Engine
[x] Rancher Prime
[x] Rancher server
[ ] Registered cluster
[x] RKE1
[x] RKE2
[x] RKE Government
[ ] Roles
[ ] UI
[x] Upstream cluster
[ ] Users
[x] Workload

sunilarjun commented 7 months ago

Core concepts/terms from Fleet to be considered: https://fleet.rancher.io/concepts

martyav commented 7 months ago

Some pages have glossaries already.

martyav commented 3 months ago

From #1125:

For the purposes of dividing up the word on definitions --

@LucasSaintarbor, could you do Managed Clusters through Rancher Enterprise, and @sunilarjun could you take RK-API through Upstream clusters? I tried to do it evenly so that we each have 8 or 9 entries.

If we add more it should be roughly, Me - Icons, Numbers, Symbols to L Lucas - M to Rancher E Sunil - Rancher F to Z

If something is already filled out, feel free to modify and review.

rancher / rancher-docs

Add a glossary of Rancher-specific terms #358