Specification / Documentation format

[thschue]

Before starting/creating specifications for the Lifecycle Toolkit, we'd like to know what you expect from a specification and in which format this should be.

There is one draft pull request open: #224.

I would propose to autogenerate the API reference from the code (similar to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/), and create issues/enhancement proposals for changes in the objects, as some changes may enforce a version change in any way. If we decide to do the specification manually, I would propose to only keep basic things of the lifecycle toolkit (Phase Model, CRDs) specified and not "overspecify."

For documentation (#141), I'd propose to stay in a very user-friendly, task-based way (also similar to Kubernetes) and as technical as necessary (we might need some code examples). If someone would like to dive deeper, there might be a link to the reference.

[mowies]

Also linking this here for completeness: #176