Create subfolders for `/docs/user` and `/docs/contributor`

[mmitoraj]

Description

Lifecycle Manager, in general, is not an end-user-facing project. Most of the documents are relevant only to those who contribute to the project; however, some documents are directed to its users.

To have a clear division of the roles we could split the /docs folder into /docs/user and /docs/contributor.

We had a case when the SRE team could not understand why the spec of a Kyma CR was different in the KCP and SKR. These were very technical details that were not explained in the Kyma CR documentation as they are not important to the users of Lifecycle Manager. However, the /docs/contributor folder could be the right location for that kind of information.

Also, looking at the folder structure of other kyma-project repositories developed by other Kyma teams, especially modules, the split into /docs/user and /docs/contributor is the template convention accepted and widely used by most of them.

TBD: The open question is how to categorize individual documents and define their final location (user vs. contributor).

Reasons

More transparent project documentation.

Assignees

@kyma-project/technical-writers @kyma-project/jellyfish

Attachments

[c-pius]

We may take this also as an opportunity to clearly defining our target groups. E.g., user: the end user of a Kyma runtime; contributor: developer or SRE (may be SAP internal or external). We also noted this here: https://github.com/kyma-project/lifecycle-manager/issues/1447

[c-pius]

As part of this refactoring and addressing new personas, we may consider to get rid of docs which seem to be obsolete anyway, i.e.:

• https://github.com/kyma-project/lifecycle-manager/blob/main/docs/developer-tutorials/prepare-gcr-registry.md
• https://github.com/kyma-project/lifecycle-manager/blob/main/docs/developer-tutorials/provision-cluster-and-registry.md
• https://github.com/kyma-project/lifecycle-manager/blob/main/docs/developer-tutorials/starting-operator-with-webhooks.md

[mmitoraj]

user - Kyma end-user contributor - LM developer or SRE module-developer - teams developing modules

Initial evaluation:

• [x] config-private-registry.md - contributor
• [x] local-test-setup.md - contributor
• [x] prepare-gcr-registry.md - ❌ to be removed
• [x] provision-cluster-and-registry.md - ❌ to be removed
• [x] starting-operator-with-webhooks.md ❌ to be removed
• [x] api/README.md - contributor
  • [x] changelog.md - contributor
  • [ ] kyma-cr.md - user + module-developer and contributor (two different versions with different details levels)
  • [x] manifest-cr.md - contributor
  • [x] moduleTemplate-cr.md contributor
• [x] architecture.md - contributor
• [x] controllers.md - contributor
• [x] running-modes.md - ❌ to be removed
• [x] 01-10-control-plane-quick-start.md - ❌ to be removed
• [x] 02-10-manage-module-with-custom-resource-policy.md - ❌ to be removed
• [x] modularization.md - ❌ to be removed
• [ ] /internal/declarative/README.md - Remove declarative library GitHub issue
• [ ] internal/manifest/README.md - contributor ?? ask the team

[mmitoraj]

As for now, we have only one doc dedicated both for the user and module provider maybe we could merge that persona into one general user.

[mmitoraj]

I would like to start referring to CRDs instead of APIs

[c-pius]

moduleTemplate-cr.md contributor

Not sure if relevant when reviewing downstream, but ModuleTemplate is also relevant for module-developer role (and neighbours team).

[mmitoraj]

Create a glossary explaining some terms, for example:

• Synchronized remote cluster
• Control Plane
• ...