Create User Docs - Explanations

[viccuad]

Following https://documentation.divio.com/explanation/, create concrete explanations for Hypper topics, such as:

• the value propositions
• how Hypper is different from Helm

[Itxaka]

isnt this covered on https://github.com/rancher-sandbox/hypper/blob/main/docs/design.md ??

[viccuad]

I think you are right, those points are covered there! Ticking them off on the issue.

My idea of the card would be to document other considered approaches to the whole problem of configuring a cluster as a system admin, and pre-emptibly explain any gotchas or compromises taken.

How about adding an explanation on the Hypper chart schema? From documentation.divio.com/explanation, I'm not thinking of a technical reference, but short explanations on why we:

• Use the chart annotations: all Hypper charts must be valid Helm charts for backwards compatibility.
• Embed a full yaml document in hypper.cattle.io/shared-dependencies: because of Kubernetes limitations. Configmaps only accept key-value pairs (not other yaml objects), therefore, we must store the yaml document in the value.

I would also like an explanation (or to expand) on why we are not pursuing Application CRDs and a more holistic approach to installing cluster services and apps.
E.g: cluster-wide CRD installations are fragile, as they are a global resource. Installing them system-wide means that all admins/users of the cluster can depend on them, and removal and update of CRDs is both opaque to all admins/users and breaks compatibility for them (see https://github.com/helm/community/blob/f9e06c16d89ccea1bea77c01a6a96ae3b309f823/architecture/crds.md).

[Itxaka]

chart schema sounds good as it seems like a basic piece of info that should be available on a mvp.

There rest seems like more advanced topics, not sure if they would fall into the mvp, but they sound good to me. New card to track those?

[viccuad]

Sounds fine here. From https://documentation.divio.com/explanation, the chart schema would be part of #83 (as a "what"), and the explanation on "why" would be here, maybe in docs/design.md
Looking at the hypper lint implementation, I was expecting to use a schema to validate hypper charts, but doesn't seem to be the case. So maybe one doesn't need a full schema for hypper charts for now? I still think it's useful to have a sole document that you can point people to, listing exactly which key-values are supported in hypper charts.

About the Application CRD approach, maybe it's a task for Matt (if we should document it, in any case).